获取 WP V2 SERP 高级结果

GET /v3/serp/wp/v2/task_get/advanced/$id

通过任务 ID 获取已完成的 WP V2 SERP 高级结果。任务在提交时计费；任务完成后，可在 30 天重复获取结果。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

> 注意：本页接口路径为 /v3/serp/wp/v2/task_get/advanced/$id。虽然页面来源路径 Yahoo 标识，但请以接口路径及创建任务时返回的 endpoint_advanced 为准。

请求地址

GET https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/$id

请求参数

参数	类型	填	说明
id	string	是	任务唯一标识，采用 UUID 格式。任务完成后 30 天可使用该 ID 查询结果。

认证方式

请求头中使用 Bearer Token：

Authorization: Bearer smt_live_YOUR_KEY

请求示例

curl

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

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

Python

import requests

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

response = requests.get(
    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",
    },
    timeout=30,
)

response.raise_for_status()
data = response.json()

# 检查接口与任务执行状态
if data["status_code"] == 20000 and data["tasks"][0]["status_code"] < 40000:
    result = data["tasks"][0]["result"]
    print(result)
else:
    print(data)

TypeScript

const taskId = "02261816-2027-0066-0000-c27d02864073";

const response = await fetch(
  `https://api.seermartech.cn/v3/serp/wp/v2/task_get/advanced/${taskId}`,
  {
    method: "GET",
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json",
    },
  }
);

if (!response.ok) {
  throw new Error(`HTTP 请求失败：${response.status}`);
}

const data = await response.json();

// 检查接口与任务执行状态
if (data.status_code === 20000 && data.tasks?.[0]?.status_code < 40000) {
  console.log(data.tasks[0].result);
} else {
  console.error(data);
}

沙盒测试

可通过沙盒端点查看高级自然搜索结果中可能返回的 SERP素及字段。沙盒使用模拟数据，不会产生费用。

GET https://api.seermartech.cn/v3/serp/yahoo/organic/task_get/advanced/00000000-0000-0000-0000-000000000000

响应结构

接口返回 JSON 对象，顶层 tasks 数组。每个任务对象对应一次任务查询结果。

{
  "version": "0.1.20220414",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1721 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "02261816-2027-0066-0000-c27d02864073",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.121 sec.",
      "cost": 0,
      "result_count": 1,
      "path": [
        "v3",
        "serp",
        "wp",
        "v2",
        "task_get",
        "advanced",
        "02261816-2027-0066-0000-c27d02864073"
      ],
      "data": {
        "api": "serp",
        "function": "task_get",
        "se": "yahoo",
        "se_type": "organic",
        "language_code": "en",
        "location_name": "United States",
        "keyword": "hotels in New York",
        "device": "mobile",
        "os": "android",
        "postback_data": "advanced"
      },
      "result": [
        {
          "keyword": "hotels in New York",
          "type": "organic",
          "se_domain": "search.yahoo.com",
          "location_code": 2840,
          "language_code": "en",
          "check_url": "https://search.yahoo.com/search?p=hotels+in+New+York",
          "datetime": "2024-01-01 12:00:00 +00:00",
          "item_types": [
            "organic",
            "paid",
            "images",
            "local_pack",
            "people_also_ask"
          ],
          "se_results_count": 0,
          "pages_count": 1,
          "items_count": 3,
          "items": [
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 1,
              "page": 1,
              "position": "left",
              "domain": "www.example.com",
              "title": "示例自然搜索结果",
              "url": "https://www.example.com/",
              "description": "示例页面描述。",
              "is_image": false,
              "is_video": false,
              "is_featured_snippet": false,
              "rectangle": null
            },
            {
              "type": "paid",
              "rank_group": 1,
              "rank_absolute": 2,
              "page": 1,
              "position": "left",
              "domain": "advertiser.example",
              "title": "示例广告结果",
              "url": "https://advertiser.example/",
              "description": "示例广告描述。",
              "extra": {
                "ad_aclk": null
              },
              "rectangle": null
            }
          ]
        }
      ]
    }
  ]
}

顶层响应字段

字段	类型	说明
version	string	当前 API 版本。
status_code	integer	接口整体状态码。建议对异常及错误状态建立处理机制。
status_message	string	接口整体状态说明。
time	string	接口执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务数量。
tasks_error	integer	返回错误的任务数量。
tasks	array	任务结果数组。

任务对象字段

字段	类型	说明
id	string	任务 UUID。
status_code	integer	任务状态码，通常在 10000 至 60000 范围。
status_message	string	任务状态说明。
time	string	任务执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的结果数量。
path	array	当前结果的接口路径。
data	object	创建任务时提交的参数。
result	array	SERP 结果数组。

SERP 结果字段

字段	类型	说明
keyword	string	创建任务时提交的。URL 编码字符会被解码，+ 会转换为空格。
type	string	搜索引擎类型。
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	搜索引擎自动纠错信息。无纠错时为 null。
refinement_chips	object	搜索细化标签；当前返回值为 null。
item_types	array	当前 SERP 中出现的结果类型。
se_results_count	integer	搜索引擎返回的结果总数。
pages_count	integer	已获取的 SERP 页数。
items_count	integer	items 数组中的数量。
items	array	SERP素数组。

spell 自动纠错字段

字段	类型	说明
keyword	string	经搜索引擎纠正后的。结果基于该返回。
type	string	自动纠错类型：did_you_mean、showing_results_for、no_results_found_for、including_results_for。

item_types 支持的类型

item_types 可能以下值：

featured_snippet
images
local_pack
hotels_pack
organic
paid
people_also_ask
related_searches
shopping
recipes
top_stories
video
ai_overview

通用 SERP素字段

除各类型专属字段外，大多数 SERP素均以下定位字段。

字段	类型	说明
type	string	SERP素类型。
rank_group	integer	同类型的排名。不同类型不计该排名。
rank_absolute	integer	SERP 中所有的绝对排名。
page	integer	素所在搜索结果页码。
position	string	素在页面中的位置：left 或 right。
xpath	string	素的 XPath 路径。
rectangle	object	素在 SERP 页面中的矩形坐标及像素尺寸。Yahoo 任务暂不支持 calculate_rectangles，因此通常为 null。

rectangle 字段

字段	类型	说明
x	integer	素左上角的 X 轴坐标，屏幕左上角为原点。
y	integer	素左上角的 Y 轴坐标，屏幕左上角为原点。
width	integer	素宽度，单位为像素。
height	integer	素高度，单位为像素。

organic 自然搜索结果

字段	类型	说明
domain	string	结果域名。
title	string	结果标题。
url	string	结果链接。
cache_url	string	页面缓存版本链接。
related_search_url	string	同一在站点上的搜索链接。
breadcrumb	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	结果图片。
amp_version	boolean	是否存在 AMP 页面版本。
rating	object	评分信息。
price	object	商品或服务价格信息。
highlighted	array	在摘要中加粗展示的词语。
links	array	附加站点链接；无数据时为 null。
faq	object	常见问题扩展；无数据时为 null。
extended_people_also_search	array	点击结果并返回搜索页后展示的搜索扩展。
about_this_result	object	“此结果”面板数据。Yahoo 搜索中不可用，固定为 null。
related_result	array	同域名结果。Yahoo 搜索中不可用，固定为 null。

图片对象

organic.images 和 featured_snippet.images 中的对象可能：

字段	类型	说明
type	string	固定为 images_element。
alt	string	图片 Alt 文本。
url	string	页面链接。
image_url	string	图片地址；源站不可用时可能返回平台存储地址。

评分对象

字段	类型	说明
rating_type	string	评分类型：Max5、Percents 或 CustomMax。
value	float	评分值。
votes_count	integer	评价数量。
rating_max	integer	当前评分类型的最大值。

价格对象

字段	类型	说明
current	float	当前价格。
regular	float	未使用折扣时的常规价格。
max_value	float	价格区间的最高价格。
currency	string	价格币种的 ISO 代码。
is_price_range	boolean	是否为价格区间。
displayed_price	string	SERP 原始展示的价格文本。

站点链接对象

字段	类型	说明
type	string	固定为 link_element。
title	string	链接标题或锚文本。
description	string	链接描述。
url	string	链接地址。

FAQ 对象

字段	类型	说明
type	string	固定为 faq_box。
items	array	FAQ 问答项。

FAQ 项目：

字段	类型	说明
type	string	固定为 faq_box_element。
title	string	问题文本。
description	string	展开后的回答。
links	array	回答中的链接。

paid 付费广告结果

字段	类型	说明
domain	string	广告主域名。
title	string	广告标题。
description	string	广告描述。
url	string	广告链接。
breadcrumb	string	广告面屑。
highlighted	array	广告描述中加粗展示的词语。
extra	object	广告附加信息。
description_rows	array	扩展广告描述；无数据时为 null。
links	array	广告附加站点链接；无数据时为 null。
price	object	广告展示的商品或服务价格信息。

paid.extra 字段

字段	类型	说明
ad_aclk	string	广告标识符。

广告附加链接除了通用站点链接字段外，还可能 ad_aclk 广告标识符。

images 图片结果

字段	类型	说明
title	string	图片结果模块标题。
url	string	图片搜索结果页链接。
items	array	图片列表；无数据时为 null。
related_image_searches	array	图片搜索建议；无数据时为 null。

图片

字段	类型	说明
type	string	固定为 images_element。
alt	string	图片 Alt 文本。
url	string	图片源页面地址。
image_url	string	压缩图片地址。

图片搜索

字段	类型	说明
type	string	固定为 related_image_searches_element。
title	string	可用于细化图片搜索的。
alt	string	推荐图片的 Alt 文本。
url	string	推荐图片源页面地址。
image_url	string	推荐图片的压缩地址。

video 视频结果

字段	类型	说明
items	array	视频列表；无数据时为 null。

视频：

字段	类型	说明
type	string	固定为 video_element。
source	string	视频来源。
title	string	视频标题。
timestamp	string	视频发布时间，UTC 格式。
url	string	视频链接。

shopping 购物结果

字段	类型	说明
title	string	购物模块标题。
items	array	商品列表；无数据时为 null。

购物：

字段	类型	说明
type	string	固定为 shopping_element。
title	string	商品标题。
price	object	商品价格信息。
source	string	商品信息来源。
description	string	商品描述。
marketplace	string	商品所在电商平台或商户托管平台。
marketplace_url	string	商品在电商平台中的页面地址。
url	string	商品链接。

featured_snippet 精选摘要

字段	类型	说明
domain	string	摘要来源域名。
title	string	结果标题。
featured_title	string	精选摘要来源页标题。
description	string	摘要。
timestamp	string	页面发布时间，UTC 格式。
url	string	来源页面链接。
images	array	图片。
table	object	摘要中的表格；无数据时为 null。

表格对象

字段	类型	说明
table_header	array	表头列名称。
table_content	array	表格，每个数组代表一行。

top_stories 热门新闻

字段	类型	说明
items	array	新闻列表；无数据时为 null。

新闻：

字段	类型	说明
type	string	固定为 top_stories_element。
source	string	新闻来源。
domain	string	来源域名。
title	string	新闻标题。
date	string	页面发布日期。
amp_version	boolean	是否存在 AMP 页面版本。
timestamp	string	新闻发布时间，UTC 格式。
url	string	新闻链接。
image_url	string	新闻图地址。

hotels_pack店结果

字段	类型	说明
title	string	店模块标题。
date_from	string	住日期，格式为 yyyy-mm-dd。
date_to	string	离店日期，格式为 yyyy-mm-dd。
items	array	店结果列表。

：

字段	类型	说明
type	string	固定为 hotels_pack_element。
price	object	指定日期对应的预订价格。
title	string	店名称。
desription	string	店描述。字段名按响应原样返回，注意拼写为 desription。
hotel_identifier	string	店唯一标识符。
domain	string	店结果域名。
url	string	店链接。
is_paid	boolean	是否为广告结果。
rating	object	店评分信息。

local_pack 本地商家结果

字段	类型	说明
title	string	商家名称。
description	string	商家描述、类别、营业状态或地址等信息。
domain	string	商家网站域名。
phone	string	商家联系电话。
url	string	商家链接。
is_paid	boolean	是否为广告结果。
rating	object	商家评分信息。
cid	string	本地商家唯一标识。

recipes 食谱结果

字段	类型	说明
items	array	食谱列表；无数据时为 null。

食谱：

字段	类型	说明
type	string	固定为 recipes_element。
title	string	食谱标题。
url	string	食谱页面链接。
domain	string	食谱来源域名。
source	string	食谱来源。
description	string	食谱摘要。
time	string	菜品准备与烹饪总时长。
rating	object	食谱评分信息。

people_also_ask 用户还会问

字段	类型	说明
items	array	问题列表；无数据时为 null。

问题：

字段	类型	说明
type	string	固定为 people_also_ask_element。
title	string	问题文本。
xpath	string	问题 XPath。
expanded_element	array	展开问题后返回的。

展开可能以下字段：

字段	类型	说明
type	string	素类型，例如 people_also_ask_expanded_element 或 people_also_ask_ai_overview_expanded_element。
featured_title	string	引用标题。
url	string	来源链接。
domain	string	来源域名。
title	string	标题。
description	string	描述。
timestamp	string	发布时间，UTC 格式。
table	object	中的表格。
items	array	AI项。

AI项可能：

字段	类型	说明
type	string	固定为 ai_overview_element。
position	string	显示位置：left 或 right。
title	string	标题。
text	string	文本或描述。
markdown	string	Markdown 格式。

related_searches 搜索

字段	类型	说明
items	array	搜索词列表；无数据时为 null。

ai_overview AI 概览

字段	类型	说明
asynchronous_ai_overview	boolean	是否异步加载。true 表示异步加载，false 表示从缓存加载。
markdown	string	AI 概览的 Markdown。
items	array	AI 概览项。
references	array	生成概览时引用的网页来源。

> 注意：当前 Yahoo 自然搜索结果中，ai_overview 的可能不可用。

references 引用来源字段

字段	类型	说明
type	string	固定为 ai_overview_reference。
source	string	引用来源名称或标题。
domain	string	引用来源域名。
url	string	引用页面地址。
title	string	引用页面标题。
text	string	用于生成 AI 概览的页面文本片段。

错误处理建议

建议同时检查顶层 status_code 与任务级 tasks[].status_code：

• 顶层 status_code = 20000：接口请求成功。
• 任务级 status_code < 40000：任务通常已成功完成，可读取 result。
• 任务级 status_code >= 40000：任务执行异常，应记录 status_message 并按业务策略重试、告警或跳过。
• result 为 null：任务可能尚未完成、已失败，或请求参数无效。

查询已完成任务前，可调用以下接口获取可用任务列表：

GET /v3/serp/wp/v2/tasks_ready

任务列表结果中通常会提供 endpoint_advanced，可直接对该路径发起 GET 请求获取高级结果。

实用场景

• 监控自然排名：提取 organic 结果的 rank_absolute、域名与 URL，持续追踪品牌站及竞品站在目标地区和语言下的排名变化。
• 识别广告竞争强度：统计 paid素、广告域名及广告文案，评估的商业竞争程度并优化投放策略。
• 挖掘选题需求：收集 people_also_ask、related_searches 与 featured_snippet 数据，构建用户问题库并规划 FAQ、指南和专题。
• 分析本地搜索机会：利用 local_pack 中的商家名称、电话、评分和 cid，识别本地服务类中的竞品与地图机会。
• 跟踪电商与结果变化：解析 shopping、hotels_pack 中的价格、评分、商品或信息，用于竞品定价监控及搜索结果页资源位分析。