获取指定任务的高级版 SERP 结果

GET /v3/serp///task_get/advanced/{id}

接口说明

通过任务 ID 获取指定搜索引擎、指定结果类型的高级版 SERP 抓取结果。

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

说明：

• ：搜索引擎名称，例如 google
• ：结果类型，例如 organic
• $id：任务唯一标识，UUID 格式

计费说明

本接口本身不会重复扣费。在创建任务时计费，任务创建后可在 30 天多次获取结果。

• 参考价请以创建任务时的接口计费为准
• 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求参数

路径参数

字段	类型	说明
id	string	任务 ID，UUID 格式
		该 ID 在本平台唯一，可在任务创建后 30 天 随时用于获取结果

沙箱测试

如需查看本接口可能返回的 SERP 特性和扩展，可调用沙箱地址：

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

说明：

• 沙箱返回该端点下所有可用类型的示例结构
• 字段为模拟数据
• 调用沙箱接口不计费

响应结构

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

顶层字段

字段	类型	说明
version	string	当前 API 版本
status_code	integer	整体状态码
status_message	string	整体状态信息
time	string	执行耗时，单位秒
cost	float	本次请求总成本，单位 USD
tasks_count	integer	tasks 数组中的任务数量
tasks_error	integer	返回错误的任务数量
tasks	array	任务结果数组

建议在业务侧实现完整的异常与错误处理逻辑。扣费请以 cost 字段为准。

tasks[] 字段

字段	类型	说明
id	string	任务 ID，UUID 格式
status_code	integer	任务状态码，范围通常为 10000-60000
status_message	string	任务状态信息
time	string	任务执行耗时
cost	float	单任务成本，单位 USD
result_count	integer	result 数组中的结果数
path	array	请求路径
data	object	创建任务时提交的参数
result	array	SERP 结果数组

result[] 通用字段

字段	类型	说明
keyword	string	创建任务时提交的；返回时会解码 %##，并将 + 解码为空格
type	string	POST 任务中的搜索类型
se_domain	string	搜索引擎域名
location_code	integer	地区代码
language_code	string	语言代码
check_url	string	对应搜索结果页直达地址，可用于结果校验
datetime	string	结果抓取时间，UTC 格式：yyyy-mm-dd hh-mm-ss +00:00
spell	object	搜索引擎自动纠错信息
refinement_chips	object	搜索细化标签
item_types	array	当前 SERP 中出现的结果类型列表
se_results_count	integer	SERP 总结果数
pages_count	integer	返回的 SERP 页数
items_count	integer	items 数组中的数量
items	array	SERP素列表

spell 字段

字段	类型	说明
keyword	string	自动纠正后的
type	string	自动纠错类型

spell.type 可选值：

• did_you_mean
• showing_results_for
• no_results_found_for
• including_results_for

refinement_chips 字段

字段	类型	说明
type	string	固定为 refinement_chips
xpath	string	素 XPath
items	array	细化项列表

refinement_chips.items[]：

字段	类型	说明
type	string	固定为 refinement_chips_element
title	string	标题
url	string	带筛选参数的搜索 URL
domain	string	SERP 中的域名
options	array	进一步细化选项

options[]：

字段	类型	说明
type	string	固定为 refinement_chips_option
title	string	标题
url	string	带筛选参数的搜索 URL
domain	string	SERP 中的域名

item_types 可选值

item_types 表示当前 SERP 中出现的结果类型，可能：

• answer_box
• app
• carousel
• multi_carousel
• featured_snippet
• google_flights
• google_reviews
• third_party_reviews
• google_posts
• images
• jobs
• knowledge_graph
• local_pack
• hotels_pack
• map
• organic
• paid
• people_also_ask
• related_searches
• people_also_search
• shopping
• top_stories
• twitter
• video
• events
• mention_carousel
• recipes
• top_sights
• scholarly_articles
• popular_products
• podcasts
• questions_and_answers
• find_results_on
• stocks_box
• visual_stories
• commercial_units
• local_services
• google_hotels
• math_solver
• currency_box
• product_considerations
• found_on_web
• short_videos
• refine_products
• explore_brands
• perspectives
• discussions_and_forums
• compare_sites
• courses
• ai_overview

---

SERP素字段说明

高级版结果会在 items[] 中返回多种 SERP素。以下保留常见与核心结构；余特殊遵循同样的对象嵌套规则，并会 type、排名、位置、XPath、字段及可选 rectangle 信息。

通用排名字段

多数 items[]素都以下字段：

字段	类型	说明
type	string	素类型
rank_group	integer	同类型分组排名
rank_absolute	integer	在整个 SERP 中的绝对排名
page	integer	所在搜索结果页码
position	string	页面位置，通常为 left 或 right
xpath	string	素 XPath
rectangle	object	素在 SERP 中的位置与尺寸；若创建任务时未设置 calculate_rectangles=true，则返回 null

rectangle：

字段	类型	说明
x	integer	左上角 x 坐标
y	integer	左上角 y 坐标
width	integer	宽度（像素）
height	integer	高度（像素）

---

1) organic 自然结果

字段	类型	说明
type	string	固定为 organic
domain	string	结果域名
title	string	标题
url	string	结果链接
cache_url	string	缓存页链接
related_search_url	string	站点搜索链接
breadcrumb	string	面屑
website_name	string	站点名称
is_image	boolean	是否图片
is_video	boolean	是否视频
is_featured_snippet	boolean	是否为精选摘要来源
is_malicious	boolean	是否被标记为恶意
is_web_story	boolean	是否为 Web Story
description	string	摘要描述
pre_snippet	string	摘要前附加信息
extended_snippet	string	摘要后附加信息
images	array	图片数组，无则为 null
amp_version	boolean	是否存在 AMP 版本
rating	object	评分信息，无则为 null
price	object	价格信息，无则为 null
highlighted	array	摘要中加粗
links	array	sitelinks，无则为 null
faq	object	FAQ 扩展，已废弃，始终返回 null
extended_people_also_search	array	返回 SERP 后可能出现的扩展搜索
about_this_result	object	“此结果”面板信息
related_result	array	同域结果
timestamp	string	发布时间，UTC 格式
rectangle	object	素位置与尺寸

images[]

字段	类型	说明
type	string	固定为 images_element
alt	string	图片 alt
url	string	页面 URL
image_url	string	图片地址

rating

字段	类型	说明
rating_type	string	评分类型：Max5、Percents、CustomMax
value	float	评分值
votes_count	integer	评价数
rating_max	integer	满分值

price

字段	类型	说明
current	float	当前价格
regular	float	原价
max_value	float	最高价格
currency	string	币种 ISO 代码
is_price_range	boolean	是否价格区间
displayed_price	string	SERP 展示的原始价格文本

links[]

字段	类型	说明
type	string	固定为 link_element
title	string	sitelink 标题
description	string	描述
url	string	链接地址
domain	string	域名

about_this_result

字段	类型	说明
type	string	固定为 about_this_result_element
url	string	结果 URL
source	string	信息来源
source_info	string	附加说明
source_url	string	来源页
language	string	结果语言
location	string	结果地区
search_terms	array	匹的搜索词
related_terms	array	搜索词

---

2) paid 广告结果

字段	类型	说明
type	string	固定为 paid
title	string	广告标题
domain	string	广告域名
website_name	string	网站名称
description	string	描述
url	string	落地页地址
breadcrumb	string	面屑
is_image	boolean	是否含图片
is_video	boolean	是否含视频
images	array	图片数组
highlighted	array	加粗词
extra	object	附加信息，例如 ad_aclk
description_rows	array	扩展描述行
links	array	广告附加链接
price	object	价格信息
rating	object	评分信息
rectangle	object	素位置与尺寸

---

3) featured_snippet 精选摘要

字段	类型	说明
type	string	固定为 featured_snippet
domain	string	来源域名
title	string	结果标题
featured_title	string	精选摘要来源标题
description	string	摘要
timestamp	string	发布时间
url	string	来源链接
images	array	图片数组
table	object	摘要表格
rectangle	object	素位置与尺寸

---

4) people_also_ask 问题

字段	类型	说明
type	string	固定为 people_also_ask
items	array	问题列表
rectangle	object	素位置与尺寸

items[]：

字段	类型	说明
type	string	固定为 people_also_ask_element
title	string	问题标题
seed_question	string	触发扩展的种子问题
xpath	string	XPath
expanded_element	array	展开后的回答

展开项可能：

• people_also_ask_expanded_element
• people_also_ask_ai_overview_expanded_element

AI 扩展结构与 ai_overview 基本一致，可能：

• title
• text
• markdown
• links
• images
• references
• asynchronous_ai_overview

---

5) ai_overview AI 概览

字段	类型	说明
type	string	固定为 ai_overview
asynchronous_ai_overview	boolean	是否异步加载
markdown	string	AI 概览的 Markdown
items	array	组成
references	array	额外参考来源
rectangle	object	素位置与尺寸

items[] 可能以下类型：

• ai_overview_element
• ai_overview_video_element
• ai_overview_table_element
• ai_overview_expanded_element

ai_overview_element

字段	类型	说明
position	string	位置
title	string	标题
text	string	文本
markdown	string	Markdown
links	array	引用链接
images	array	图片
references	array	参考来源

ai_overview_reference

字段	类型	说明
type	string	固定为 ai_overview_reference
source	string	来源名称
domain	string	来源域名
url	string	来源页面地址
title	string	来源标题
text	string	被引用文本片段

---

6) knowledge_graph 知识图谱

注意：在移动端结果中，knowledge_graph 项目可能被打断，因此响应中可能出现多个 knowledge_graph 块。

字段	类型	说明
type	string	固定为 knowledge_graph
title	string	实体名称
subtitle	string	副标题
description	string	描述
card_id	string	卡片 ID
url	string	官方或链接
image_url	string	主图
logo_url	string	Logo
cid	string	搜索引擎定义的实体 ID
items	array	知识图谱组件
rectangle	object	素位置与尺寸

组件可能：

• knowledge_graph_images_item
• knowledge_graph_list_item
• knowledge_graph_ai_overview_item
• knowledge_graph_description_item
• knowledge_graph_row_item
• knowledge_graph_carousel_item
• knowledge_graph_part_item
• knowledge_graph_expanded_item
• knowledge_graph_shopping_item
• knowledge_graph_hotels_booking_item

这些结构通常会：

• title
• text
• data_attrid
• link 或 links
• items
• table
• images
• timestamp
• rectangle

---

7) 常见

以下也会出现在 items[] 中，字段模式与上述结构一致，通常标题、链接、子项目、评分、价格、时间、图片、坐标等信息：

• answer_box
• carousel
• multi_carousel
• related_searches
• people_also_search
• local_pack
• hotels_pack
• top_stories
• twitter
• map
• google_flights
• google_reviews
• third_party_reviews
• google_posts
• video
• app
• images
• shopping
• jobs
• events
• mention_carousel
• recipes
• top_sights
• scholarly_articles
• popular_products
• podcasts
• questions_and_answers
• find_results_on
• stocks_box
• visual_stories
• commercial_units
• local_services
• google_hotels
• math_solver
• currency_box
• courses
• product_considerations
• short_videos
• found_on_web
• refine_products
• explore_brands
• perspectives
• discussions_and_forums
• compare_sites

如果你需要做强类型解析，建议按 type 分发解析器，并为以下字段设计可选结构：

• items
• links
• images
• rating
• price
• table
• graph
• expanded_element
• references
• rectangle

错误处理建议

请重点处理以下：

• 顶层 status_code 非成功状态
• tasks_error > 0
• tasks[].status_code >= 40000
• tasks[].result 为空
• 结果中部分嵌套对象为 null

建议根据 /v3/appendix/errors 对状态码进行分类处理。

请求示例

cURL

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

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

Python

import requests

task_id = "02261816-2027-0066-0000-c27d02864073"
url = f"https://api.seermartech.cn/v3/serp/{{low_se_name}}/{{low_se_type}}/task_get/advanced/{task_id}"

headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
data = response.json

print(data)

TypeScript

import axios from "axios";

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

axios({
 method: "get",
 url: `https://api.seermartech.cn/v3/serp/{{low_se_name}}/{{low_se_type}}/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);
 });

响应示例

下面是精简后的响应结构示例，展示主要层级与常见：

{
 "version": "0.1.20200129",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.3059 sec.",
 "cost": 0.003,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "id": "02261816-2027-0066-0000-c27d02864073",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1023 sec.",
 "cost": 0,
 "result_count": 1,
 "path": [
 "v3",
 "serp",
 "google",
 "organic",
 "task_get",
 "advanced"
 ],
 "data": {
 "api": "serp",
 "function": "task_get",
 "se": "google",
 "se_type": "organic",
 "language_name": "English",
 "location_name": "United States",
 "keyword": "flight ticket new york san francisco",
 "tag": "tag2",
 "device": "desktop",
 "os": "windows"
 },
 "result": [
 {
 "keyword": "flight ticket new york san francisco",
 "type": "organic",
 "se_domain": "google.com",
 "location_code": 2840,
 "language_code": "en",
 "datetime": "2024-04-26 00:00:00 +00:00",
 "item_types": [
 "organic",
 "paid",
 "people_also_ask",
 "featured_snippet",
 "ai_overview",
 "knowledge_graph"
 ],
 "se_results_count": 85600000,
 "pages_count": 1,
 "items_count": 6,
 "items": [
 {
 "type": "organic",
 "rank_group": 26,
 "rank_absolute": 30,
 "page": 1,
 "position": "left",
 "domain": "www.t-mobile.com",
 "title": "Apple iPhone 12 Pro 5G | 4 colors in 512GB, 256GB & 128GB",
 "url": "https://www.t-mobile.com/cell-phone/apple-iphone-12-pro",
 "breadcrumb": "https://www.t-mobile.com › Phones › Apple",
 "website_name": "T-Mobile",
 "description": "Get a great deal on the 5G-ready Apple iPhone 12 Pro.",
 "rating": {
 "rating_type": "Max5",
 "value": 4,
 "votes_count": 231,
 "rating_max": 5
 },
 "price": {
 "current": 30,
 "regular": null,
 "max_value": 899.99,
 "currency": "USD",
 "is_price_range": true,
 "displayed_price": "US$30.00 to US$899.99"
 },
 "about_this_result": {
 "type": "about_this_result_element",
 "url": "https://www.t-mobile.com/cell-phone/apple-iphone-12-pro",
 "source": "Wikipedia",
 "language": "English"
 },
 "rectangle": {
 "x": 180,
 "y": 5814,
 "width": 652,
 "height": 363
 }
 },
 {
 "type": "paid",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "position": "left",
 "title": "Cheap Flights to Boston - Roundtrip starting from $97",
 "domain": "www.expedia.com",
 "website_name": "Expedia",
 "url": "https://www.expedia.com/Cheap-Flights-To-Boston.d178239.Travel-Guide-Flights",
 "description": "How can Expedia help you save?",
 "extra": {
 "ad_aclk": "DChcSEwjvwqLQ0MT8AhVH7FEKHWo_D70YABAAGgJ3cw"
 },
 "rating": {
 "rating_type": "Max5",
 "value": 4.8,
 "votes_count": 803,
 "rating_max": 5
 }
 },
 {
 "type": "people_also_ask",
 "rank_group": 1,
 "rank_absolute": 3,
 "page": 1,
 "position": "left",
 "items": [
 {
 "type": "people_also_ask_element",
 "title": "What is the difference between HIDS and NIDS?"
 }
 ]
 },
 {
 "type": "featured_snippet",
 "rank_group": 1,
 "rank_absolute": 10,
 "page": 1,
 "position": "left",
 "domain": "www.rome.net",
 "title": "Rome Metro - Lines, hours, fares and Rome metro maps",
 "description": "Most important metro stations...",
 "timestamp": "2020-09-11 14:42:55 +00:00",
 "url": "https://www.rome.net/metro"
 },
 {
 "type": "knowledge_graph",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "position": "right",
 "title": "Eminem",
 "subtitle": "American rapper",
 "description": "Marshall Bruce Mathers III, known professionally as Eminem...",
 "card_id": "/m/01vsgrn",
 "url": "http://www.eminem.com/"
 },
 {
 "type": "ai_overview",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "position": "left",
 "asynchronous_ai_overview": false,
 "markdown": "AI overview content in markdown",
 "items": [
 {
 "type": "ai_overview_element",
 "title": "Overview",
 "text": "The BMW M4 F82 is a high-performance coupe..."
 }
 ]
 }
 ]
 }
 ]
 }
 ]
}

使用建议

1. 推荐流程

1. 通过任务创建接口提交抓取任务
2. 通过 /v3/serp///tasks_ready 获取已完成任务
3. 使用本接口按 id 拉取高级版完整结果

2. 结果解析建议

由于高级版 SERP 会返回大量异构，建议：

• 按 items[].type 建立分类型解析逻辑
• 对 null 值做容
• 对 AI 概览、知识图谱、PAA、购物、地图、本地等特殊模块单独建模
• 如果需要页面可视化分析，可在创建任务时启用 calculate_rectangles

实用场景

• 监控版位结构：识别自然结果、广告、精选摘要、AI 概览等模块占比，评估目标词真实可见性。
• 解析 SERP 特征机会：提取 people_also_ask、related_searches、featured_snippet 等模块，选题与问答布局。
• 追踪竞品形态：分析竞品在自然结果、购物、知识图谱、本地中的出现方式，支持 SEO 与投放联动优化。
• 评估 AI 概览影响：抓取 ai_overview 及引用来源，判断品牌或站点是否 AI 回答链路。
• 构建搜索可视化报告：结合 rank_absolute、position、rectangle 生成页面布局报告，量化不同模块对点击机会的挤压程度。