SeerMarTech API 文档

主题

获取新闻 SERP 高级结果（按任务 ID） ​

接口说明 ​

用于根据任务 ID 获取已提交新闻搜索任务的高级结果。

  • 请求方式：GET
  • 接口地址：https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/$id

说明：

  • $id 为任务唯一标识，格式为 UUID
  • 任务结果在任务提交后的 30 天 可重复获取
  • 在创建任务时计费，获取结果本身不重复收费
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

说明：该接口路径为平台容路径，文档中按原路径保留。

计费说明 ​

本接口本身不会因重复获取结果而额外计费；费用发生在对应任务创建时。 如果本次结果查询返回 cost，通常为 0。

路径参数 ​

参数名类型说明
idstring任务 ID，UUID 格式的唯一标识符；可在 30 天随时用于查询任务结果

沙箱调试 ​

如需查看该接口可能返回的 SERP素结构，可调用沙箱接口：

https://sandbox.seermartech.cn/v3/serp/google/news/task_get/advanced/00000000-0000-0000-0000-000000000000

说明：

  • 沙箱返回的是模拟数据的完整字段结构
  • 可用于联调解析逻辑
  • 调用沙箱接口不会产生费用

返回结果结构 ​

接口返回 JSON，顶层 tasks 数组。

顶层字段 ​

字段类型说明
versionstring当前 API 版本
status_codeinteger通用状态码
status_messagestring通用状态信息
timestring接口执行时间，单位秒
costfloat本次请求总成本，单位 USD
tasks_countintegertasks 数组中的任务数量
tasks_errorinteger返回错误的任务数量
tasksarray任务结果数组

建议在接时设计完善的异常处理逻辑，并根据 status_code、status_message 判断任务状态与错误类型。

tasks 数组字段 ​

字段类型说明
idstring任务 ID，UUID 格式
status_codeinteger任务状态码，通常在 10000-60000 范围
status_messagestring任务状态说明
timestring任务执行时间
costfloat任务成本，单位 USD
result_countintegerresult 数组中的数量
patharray请求路径
dataobject创建任务时传的参数
resultarray获取结果数组

result 数组字段 ​

字段类型说明
keywordstring创建任务时的；返回时会对 %## 进行解码，+ 会被解码为空格
typestringPOST 提交时指定的搜索引擎类型
se_domainstringPOST 提交时指定的搜索引擎域名
location_codeintegerPOST 提交时指定的地区代码
language_codestringPOST 提交时指定的语言代码
check_urlstring结果页直达链接，可用于人工校验采集准确性
datetimestring抓取结果时间，UTC 格式：yyyy-mm-dd hh:mm:ss +00:00
spellobject搜索引擎自动纠错信息
refinement_chipsobject搜索细化推荐项
includes_non_news_search_resultsboolean是否除新闻外还非新闻搜索结果
item_typesarray当前 SERP 中出现的结果类型
se_results_countintegerSERP 结果总量
items_countintegeritems 数组中的结果数量
itemsarraySERP 中解析出的结果项

spell 字段 ​

当搜索引擎对进行了自动纠错时返回。

字段类型说明
keywordstring自动纠错后的
typestring自动纠错类型

type 可选值：

  • did_you_mean
  • showing_results_for
  • no_results_found_for
  • including_results_for

refinement_chips 字段 ​

搜索结果页中的推荐筛选项。

字段类型说明
typestring固定为 refinement_chips
xpathstring素的 XPath
itemsarray推荐筛选项列表

refinement_chips.items 字段 ​

字段类型说明
typestring固定为 refinement_chips_element
titlestring筛选项标题
urlstring带筛选参数的搜索链接
domainstringSERP 中展示的域名
optionsarray更多筛选选项

refinement_chips.items.options 字段 ​

字段类型说明
typestring固定为 refinement_chips_option
titlestring选项标题
urlstring带筛选参数的搜索链接
domainstringSERP 中展示的域名

items 数组支持的结果类型 ​

item_types / items[].type 可能以下值：

  • top_stories
  • news_search

news_search 结果字段 ​

表示普通新闻搜索结果项。

字段类型说明
typestring固定为 news_search
rank_groupinteger同类型结果组排名
rank_absoluteintegerSERP局绝对排名
xpathstring素 XPath
domainstring结果域名
titlestring新闻标题
urlstring结果链接
image_urlstring图链接，可能指向原站资源或平台缓存资源
snippetstring摘要文本
time_publishedstring发布时间的相对描述
timestampstring新闻发布时间，格式如 2019-11-15 12:57:46 +00:00
rectangleobject素在 SERP 页面中的矩形坐标信息；若创建任务时未设置 calculate_rectangles=true，则为 null

rectangle 字段 ​

字段类型说明
xinteger左上角 x 坐标
yinteger左上角 y 坐标
widthinteger素宽度，像素
heightinteger素高度，像素

top_stories 结果字段 ​

表示 SERP 中的“头条新闻 / Top Stories”模块。

字段类型说明
typestring固定为 top_stories
rank_groupinteger同类型结果组排名
rank_absoluteintegerSERP局绝对排名
positionstring模块在页面中的对齐位置；当前可为 left
xpathstring素 XPath
titlestring模块标题
itemsarray模块的新闻条目；若无则为 null
rectangleobject模块在 SERP 页面中的矩形坐标信息；若未启用 calculate_rectangles，则为 null

top_stories.items 字段 ​

字段类型说明
typestring固定为 top_stories_element
sourcestring新闻来源名称
domainstring新闻来源域名
titlestring新闻标题
datestring相对发布时间，例如 23 hours ago
amp_versionboolean是否提供 AMP 版本
timestampstring新闻发布时间，格式如 2019-11-15 12:57:46 +00:00
urlstring新闻链接
image_urlstring图片链接，可能指向原站资源或平台缓存资源
rectangleobject条目在 SERP 中的矩形坐标信息

调用示例 ​

curl ​

bash
id="02261816-2027-0066-0000-c27d02864073"

curl --location --request GET "https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/${id}" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json"

Python ​

python
import requests

task_id = "02231256-2604-0066-2000-57133b8fc54e"

url = f"https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/{task_id}"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.status_code)
print(response.json)

TypeScript ​

typescript
import axios from "axios";

const taskId = "02231256-2604-0066-2000-57133b8fc54e";

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/${taskId}`,
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json",
 },
})
 .then((response) => {
 // 输出结果数据
 console.log(response.data);
 })
 .catch((error) => {
 console.error(error);
 });

响应示例 ​

json
{
 "version": "0.1.20200923",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.0733 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "google",
 "se_type": "news",
 "language_code": "en",
 "location_code": "2840",
 "keyword": "android",
 "device": "desktop",
 "calculate_rectangles": true,
 "depth": 5,
 "os": "windows"
 },
 "result": [
 {
 "se_results_count": 771000000,
 "items_count": 100,
 "items": [
 {
 "type": "news_search",
 "rank_group": 1,
 "rank_absolute": 1,
 "xpath": "/body/div/div/div/div/div/div/div/div/div/div",
 "domain": "www.eff.org",
 "title": "VICTORY: Google Releases “disable 2g” Feature for New Android Smartphones",
 "url": "https://www.eff.org/deeplinks/2022/01/victory-google-releases-disable-2g-feature-new-android-smartphones",
 "image_url": "https://api.seermartech.cn/cdn/i/01132007-1535-0139-0000-7b275022ce6d:0",
 "snippet": "Last year Google quietly pushed a new feature to its Android operating system allowing users to optionally disable 2G at the modem level in...",
 "time_published": null,
 "timestamp": "2022-01-12 22:07:51 +00:00",
 "rectangle": {
 "x": 180,
 "y": 182,
 "width": 652,
 "height": 178
 }
 },
 {
 "type": "top_stories",
 "rank_group": 1,
 "rank_absolute": 2,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/g-section-with-header",
 "title": "Nvidia's Shield TVs get Android 11 upgrade",
 "items": [],
 "rectangle": {
 "x": 180,
 "y": 376,
 "width": 652,
 "height": 325
 }
 },
 {
 "type": "news_search",
 "rank_group": 2,
 "rank_absolute": 3,
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/div",
 "domain": "www.cnet.com",
 "title": "Nvidia's GeForce Now service can stream Fortnite on iPhone and Android",
 "url": "https://www.cnet.com/tech/gaming/nvidias-geforce-now-service-can-stream-fortnite-on-iphone-and-android/",
 "image_url": "https://api.seermartech.cn/cdn/i/01132007-1535-0139-0000-7b275022ce6d:1",
 "snippet": "The game streaming service, offered by chipmaker Nvidia, has new touch controls to make it easier to play the game too.",
 "time_published": null,
 "timestamp": "2022-01-13 17:07:51 +00:00",
 "rectangle": {
 "x": 180,
 "y": 729,
 "width": 652,
 "height": 178
 }
 },
 {
 "type": "top_stories",
 "rank_group": 2,
 "rank_absolute": 4,
 "position": "left",
 "xpath": "/html/body/div/div/div/div/div/div/div/div/div/g-section-with-header",
 "title": "News about Android",
 "items": [],
 "rectangle": {
 "x": 180,
 "y": 923,
 "width": 652,
 "height": 325
 }
 }
 ]
 }
 ]
 }
 ]
}

状态码与错误处理 ​

请重点检查以下字段：

  • 顶层：status_code、status_message
  • 任务层：tasks[].status_code、tasks[].status_message

建议处理方式：

  1. 判断 HTTP 状态码是否正常；
  2. 再判断顶层 status_code 是否成功；
  3. 遍历 tasks，逐个判断任务级状态；
  4. 如果 result 为空，需结合任务状态码判断是否任务未完成、参数有误或结果为空。

完整错误码说明请参考错误码文档。

实用场景 ​

  • 拉取新闻 SERP 结果：根据已创建任务 ID 获取新闻搜索完整结果，用于构建新闻可见性监控看板。
  • 识别 Top Stories 曝机会：分析 top_stories 模块出现频率、标题与来源，评估品牌或专题头条新闻模块的机会。
  • 追踪新闻来源分布：基于 domain、source 字段统计主要媒体来源，判断行业话题被哪些站点主导。
  • 校验页面布局与首屏占位：结合 rectangle 坐标分析新闻结果在 SERP 中的位置和尺寸，用于研究点击可见性。
  • 监控新闻热度变化：持续查询同一类任务结果，对比 items_count、se_results_count 和新闻发布时间，识别热点事件升温趋势。

统一入口：官网 · LLM API · 控制台

© 2026 SeerMarTech · GEO · SEO 营销数据 API