Yahoo 实时高级 SERP

POST /v3/serp/wp/organic/live/advanced

本接口用于实时获取 Yahoo 搜索结果页（SERP）的高级结构化数据。结果会根据指定的地理位置、语言、设备及操作系统返回，自然结果、广告、图片、视频、购物、精选摘要、本地结果、新闻、搜索等 SERP素。

请求体使用 UTF-8 编码的 JSON 数组格式。实时接口单次请求平台限流以认证说明中的 30/60/120 次/分钟规则为准。

每次请求均会产生费用；当请求需要抓取多个结果页时，将按抓取的 SERP 页数计费。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求参数

字段	类型	填	说明
url	string	否	搜索请求的直接 URL。本接口会尝试从 URL 中解析参数。该方式处理复杂，且 URL 中准确语言和地区信息，通常建议优使用 keyword、位置和语言参数。示例：https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8。
keyword	string	是	搜索，最长 700 个字符。%## 会被解码，+ 会被解码为空格。如本身 %，应写为 %25；如需保留 +，应写为 %2B。
location_name	string	条件填	搜索地区名。未提供 location_code 或 location_coordinate 时填；使用该字段后无需再传位置字段。示例：London,England,United Kingdom。
location_code	integer	条件填	搜索地区代码。未提供 location_name 或 location_coordinate 时填；使用后无需再传位置字段。示例：2840。
location_coordinate	string	条件填	GPS 坐标，格式为 latitude,longitude,radius。未提供 location_name 或 location_code 时填。纬度、经度最多 7 位小数；radius 范围为 199.9 至 199999。示例：53.476225,-2.243572,200。
language_name	string	条件填	搜索语言名。未提供 language_code 时填。示例：English。
language_code	string	条件填	搜索语言代码。未提供 language_name 时填。示例：en。
device	string	否	设备类型：desktop 或 mobile。默认：desktop。
os	string	否	操作系统。device=desktop 时可选 windows、macos，默认 windows；device=mobile 时可选 android、ios，默认 android。
se_domain	string	否	搜索引擎域名。系统会根据位置和语言自动选择，也可手动指定，例如 au.search.yahoo.com、uk.search.yahoo.com、ca.search.yahoo.com。
depth	integer	否	需要解析的 SERP 结果数量。默认 6，最大 200。Yahoo 单页结果可能少于 10 条，设置更大的值可能触发多页抓取和额外费用。
max_crawl_pages	integer	否	最大抓取搜索结果页数。默认 1，最大 100。该参数与 depth合使用。
target	string	否	返回与指定域名、子域名或页面匹的结果。域名或子域名不可 https:// 与 www.。 url 字段的 SERP素会参与匹。支持 _ 通符。
search_param	string	否	搜索请求的附加参数。
stop_crawl_on_match	array	否	停止继续抓取的目标规则数组，最多 10 个对象。命中后，响应将返回截至该目标为止的结果。计费覆盖从开始抓取至满足停止条件期间的 SERP 页面。
stop_crawl_on_match[].match_value	string	条件填	匹目标值；当指定 stop_crawl_on_match 时填。可为域名、子域名或通符模式。域名不可带协议。示例：example.com、/blog/post-*。
stop_crawl_on_match[].match_type	string	条件填	匹类型；当指定 stop_crawl_on_match 时填。可选：domain、with_subdomains、wildcard。
tag	string	否	自定义任务标识，最长 255 个字符。返回结果中的 data.tag 会保留该值，便于请求与结果。

target 匹规则

示例	匹范围
example.com	网站首页 URL，例如 https://example.com、https://www.example.com/。
example.com*	指定域名下的页面。
*example.com*	指定主域名及子域名、页面。
*example.com	任意子域名下的首页。
example.com/example-page	精确匹指定 URL。
example.com/example-page*	匹以指定字符串开头的 URL。

请求示例

curl

curl --location --request POST \
  "https://api.seermartech.cn/v3/serp/wp/organic/live/advanced" \
  --header "Authorization: Bearer smt_live_YOUR_KEY" \
  --header "Content-Type: application/json" \
  --data-raw '[
    {
      "keyword": "hotels in New York",
      "language_code": "en",
      "location_code": 2840,
      "device": "mobile",
      "os": "android",
      "depth": 20,
      "tag": "yahoo-hotel-serp"
    }
  ]'

Python

import requests

url = "https://api.seermartech.cn/v3/serp/wp/organic/live/advanced"

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

# 实时接口一次支持一个任务，仍须以 JSON 数组提交
payload = [
    {
        "keyword": "hotels in New York",
        "language_code": "en",
        "location_code": 2840,
        "device": "mobile",
        "os": "android",
        "depth": 20,
        "tag": "yahoo-hotel-serp"
    }
]

response = requests.post(url, headers=headers, json=payload, timeout=60)
response.raise_for_status()

result = response.json()
if result["status_code"] == 20000:
    print(result)
else:
    print(f'请求失败：{result["status_code"]} - {result["status_message"]}')

TypeScript

import axios from "axios";

const response = await axios.post(
  "https://api.seermartech.cn/v3/serp/wp/organic/live/advanced",
  [
    {
      keyword: "hotels in New York",
      language_code: "en",
      location_code: 2840,
      device: "mobile",
      os: "android",
      depth: 20,
      tag: "yahoo-hotel-serp"
    }
  ],
  {
    headers: {
      Authorization: "Bearer smt_live_YOUR_KEY",
      "Content-Type": "application/json"
    }
  }
);

const result = response.data;

if (result.status_code === 20000) {
  console.log(result);
} else {
  console.error(`请求失败：${result.status_code} - ${result.status_message}`);
}

响应结构

接口返回 JSON 对象任务状态、执行耗时、费用信息以及解析后的 SERP 数据。

顶层字段

字段	类型	说明
version	string	当前 API 版本。
status_code	integer	局状态码。20000 表示请求成功。应针对异常状态设计重试、告警或降级处理逻辑。
status_message	string	局状态说明。
time	string	请求执行耗时，单位为秒。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
tasks_count	integer	tasks 数组中的任务总数。
tasks_error	integer	返回错误的任务数量。
tasks	array	任务结果数组。

tasks[] 任务字段

字段	类型	说明
id	string	平台任务唯一标识，UUID 格式。
status_code	integer	任务状态码。
status_message	string	任务状态说明。
time	string	任务执行耗时。
cost	float	平台原始 USD 成本兼容字段；人民币实扣以 X-SeerMarTech-Charge-CNY 为准。
result_count	integer	result 数组中的结果对象数量。
path	array	请求路径信息。
data	object	回显的请求任务参数。
result	array	SERP 解析结果数组。

result[] 搜索结果信息

字段	类型	说明
keyword	string	已解码的搜索。+ 会被返回为空格。
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。
spell.keyword	string	自动纠正后的。
spell.type	string	自动纠错类型：did_you_mean、showing_results_for、no_results_found_for、including_results_for。
refinement_chips	object	搜索细化标签。该字段为 null。
item_types	array	当前 SERP 中出现的类型。
se_results_count	integer	搜索引擎显示的结果总数。
pages_count	integer	实抓取的 SERP 页数。
items_count	integer	items 数组中的数量。
items	array	SERP素数组。

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	素类型。
rank_group	integer	同类型中的排名，不计算类型。
rank_absolute	integer	在整页 SERP 中的绝对位置。
page	integer	素所在的搜索结果页码。
position	string	页面布局位置：left 或 right。
xpath	string	素在页面中的 XPath 路径。
rectangle	object / null	素在页面中的坐标与尺寸。Yahoo 任务暂不支持 calculate_rectangles，因此通常为 null。
rectangle.x	integer	素左上角 X 坐标。
rectangle.y	integer	素左上角 Y 坐标。
rectangle.width	integer	素宽度，单位为像素。
rectangle.height	integer	素高度，单位为像素。

##素类型说明

organic：自然搜索结果

字段	类型	说明
domain	string	结果域名。
title	string	标题。
url	string	结果 URL。
cache_url	string	缓存页面 URL。
related_search_url	string	站点搜索 URL。
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	FAQ 扩展；不存在时为 null。
extended_people_also_search	array	点击结果后返回 SERP 时出现的搜索扩展。
about_this_result	object	“此结果”面板信息。Yahoo 不支持，该字段始终为 null。
related_result	array	同域名结果。Yahoo 不支持，该字段始终为 null。

organic.images[]

字段	类型	说明
type	string	固定为 images_element。
alt	string	图片 alt 文本。
url	string	页面 URL。
image_url	string	图片 URL；原图不可用时可能为平台缓存地址。

organic.rating

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

organic.price、paid.price、shopping.items[].price、hotels_pack.items[].price

字段	类型	说明
current	float	当前价格。
regular	float	原价或非折扣价格。
max_value	float	价格区间上限。
currency	string	价格币种 ISO 代码。
is_price_range	boolean	是否为价格区间。
displayed_price	string	SERP 原始展示价格文本。

organic.links[]

字段	类型	说明
type	string	固定为 link_element。
title	string	链接标题。
description	string	链接描述。
url	string	链接 URL。

organic.faq

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

organic.faq.items[] 中每项的 type 为 faq_box_element， title（问题）、description（答案）和 links（引用链接数组）。

paid：广告结果

字段	类型	说明
domain	string	广告结果域名。
title	string	广告标题。
description	string	广告描述。
url	string	广告跳转 URL。
breadcrumb	string	广告面屑文本。
highlighted	array	描述中的高亮词。
extra	object	广告扩展信息。
extra.ad_aclk	string	广告标识符。
description_rows	array	扩展描述行；无数据时为 null。
links	array	广告附加链接。
price	object	广告商品或服务价格信息。

广告附加链接 links[] 的 type 为 link_element，可 title、description、url 和 ad_aclk。

images：图片结果模块

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

items[] 的 type 为 images_element，：

字段	类型	说明
alt	string	图片 alt 文本。
url	string	原始图片页面 URL。
image_url	string	压缩图片 URL 或缓存图片 URL。

related_image_searches[] 的 type 为 related_image_searches_element， title、alt、url 和 image_url。

video：视频结果模块

items[] 中每项的 type 为 video_element，可：

字段	类型	说明
source	string	视频来源。
title	string	视频标题。
timestamp	string	发布时间，UTC 格式。
url	string	视频 URL。

shopping：购物结果模块

字段	类型	说明
title	string	购物模块标题。
items	array	购物项数组。

items[] 的 type 为 shopping_element，：

字段	类型	说明
title	string	商品标题。
price	object	商品价格。
source	string	商品信息来源。
description	string	商品描述。
marketplace	string	商家或聚合商城名称。
marketplace_url	string	商城商品页 URL。
url	string	商品 URL。

featured_snippet：精选摘要

字段	类型	说明
domain	string	来源域名。
title	string	结果标题。
featured_title	string	精选摘要来源页标题。
description	string	摘要。
timestamp	string	发布时间，UTC 格式。
url	string	来源 URL。
images	array	摘要图片。
table	object	表格结果；不存在时为 null。

table.table_header 为列名数组，table.table_content 为表格行数据数组。

top_stories：热门新闻

items[] 中每项的 type 为 top_stories_element，：

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

hotels_pack：结果模块

字段	类型	说明
title	string	店模块标题。
date_from	string	住日期，格式 yyyy-mm-dd。
date_to	string	离店日期，格式 yyyy-mm-dd。
items	array	店条目数组。

items[] 的 type 为 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[] 中每项的 type 为 recipes_element，：

字段	类型	说明
title	string	食谱标题。
url	string	食谱页面 URL。
domain	string	来源域名。
source	string	信息来源。
description	string	食谱摘要。
time	string	烹饪总耗时。
rating	object	食谱评分信息。

people_also_ask：用户还会问

items[] 中每项的 type 为 people_also_ask_element，：

字段	类型	说明
title	string	问题文本。
xpath	string	问题 XPath。
expanded_element	array	展开问题后获得的。

expanded_element[] 可能以下字段：

字段	类型	说明
type	string	可能为 people_also_ask_expanded_element 或 people_also_ask_ai_overview_expanded_element。
featured_title	string	来源标题。
url	string	来源 URL。
domain	string	来源域名。
title	string	结果标题。
description	string	答案摘要。
timestamp	string	发布时间，UTC 格式。
table	object	表格。
items	array	AI 概览项。

AI 概览项的 type 为 ai_overview_element，可 position、title、text 和 markdown。

related_searches：搜索

该表示与当前的搜索建议。items 为搜索项数组；当无数据时为 null。

ai_overview：AI 概览

字段	类型	说明
asynchronous_ai_overview	boolean	true 表示该异步加载；false 表示从缓存加载。
markdown	string	AI 概览 Markdown。
items	array	AI 概览项。
references	array	用于生成 AI 概览的参考来源。

> Yahoo 自然搜索结果当前不提供 ai_overview 的，因此字段可能为 null 或空数组。

ai_overview.items[] 中每项的 type 为 ai_overview_element，可：

字段	类型	说明
position	string	素布局位置：left 或 right。
title	string	标题。
text	string	文本或摘要。
markdown	string	Markdown 格式。

ai_overview.references[] 中每项的 type 为 ai_overview_reference，：

字段	类型	说明
source	string	参考来源名称或标题。
domain	string	参考页面域名。
url	string	参考页面 URL。
title	string	参考页面标题。
text	string	用于生成概览的页面文本片段。

响应示例

{
  "version": "0.1.20220414",
  "status_code": 20000,
  "status_message": "Ok.",
  "time": "0.1721 sec.",
  "cost": 0,
  "tasks_count": 1,
  "tasks_error": 0,
  "tasks": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "status_code": 20000,
      "status_message": "Ok.",
      "time": "0.1721 sec.",
      "cost": 0,
      "result_count": 1,
      "data": {
        "api": "serp",
        "function": "live",
        "se": "yahoo",
        "se_type": "organic",
        "language_code": "en",
        "location_name": "United States",
        "keyword": "hotels in New York",
        "device": "mobile",
        "os": "android",
        "tag": "yahoo-hotel-serp"
      },
      "result": [
        {
          "keyword": "hotels in New York",
          "type": "organic",
          "se_domain": "search.yahoo.com",
          "location_code": 2840,
          "language_code": "en",
          "datetime": "2025-01-01 12:00:00 +00:00",
          "item_types": [
            "paid",
            "featured_snippet",
            "organic",
            "hotels_pack",
            "local_pack",
            "images",
            "related_searches"
          ],
          "se_results_count": 0,
          "pages_count": 1,
          "items_count": 3,
          "items": [
            {
              "type": "paid",
              "rank_group": 1,
              "rank_absolute": 1,
              "page": 1,
              "position": "left",
              "domain": "example-hotel.com",
              "title": "纽约优惠",
              "description": "立即预订纽约，享受限时优惠。",
              "url": "https://example-hotel.com/new-york",
              "highlighted": null,
              "extra": {
                "ad_aclk": null
              },
              "links": null,
              "price": null,
              "rectangle": null
            },
            {
              "type": "organic",
              "rank_group": 1,
              "rank_absolute": 2,
              "page": 1,
              "position": "left",
              "domain": "www.example.com",
              "title": "纽约预订与住宿指南",
              "url": "https://www.example.com/new-york-hotels",
              "breadcrumb": "www.example.com > Travel > New York",
              "is_image": false,
              "is_video": false,
              "is_featured_snippet": false,
              "is_malicious": false,
              "is_web_story": false,
              "description": "查看纽约热门、价格和预订建议。",
              "images": null,
              "rating": null,
              "price": null,
              "links": null,
              "faq": null,
              "about_this_result": null,
              "related_result": null,
              "rectangle": null
            },
            {
              "type": "local_pack",
              "rank_group": 1,
              "rank_absolute": 3,
              "page": 1,
              "position": "left",
              "title": "示例",
              "description": " · 营业中 · 纽约市",
              "domain": "example-hotel.com",
              "phone": "+1-212-000-0000",
              "url": "https://example-hotel.com",
              "is_paid": false,
              "rating": {
                "rating_type": "Max5",
                "value": 4.5,
                "votes_count": 1200,
                "rating_max": 5
              },
              "cid": "123456789",
              "rectangle": null
            }
          ]
        }
      ]
    }
  ]
}

错误处理

建议同时检查顶层 status_code 与每个 tasks[].status_code：

• 20000：请求成功。
• 非 20000：请求或任务处理失败，应读取对应的 status_message 获取原因。
• 当 tasks_error 大于 0 时，表示至少一个任务执行异常。
• 对网络时、限流、参数错误和临时服务异常，建议建立重试、告警与日志记录机制。
• 任务级错误不一定导致整个 HTTP 请求失败，因此不能依赖 HTTP 状态码判断业务结果。

实用场景

• 监测 Yahoo 排名：按国家、城市、语言和设备抓取自然结果，持续跟踪品牌站、竞品站或页面的排名变化。
• 识别竞品广告投放：提取 paid 广告结果、广告标题和跳转链接，评估竞品在目标上的搜索广告覆盖。
• 挖掘选题机会：分析 people_also_ask、related_searches、精选摘要和自然结果摘要，构建用户问题库与长尾单。
• 评估本地搜索：通过 local_pack 获取商家名称、电话、评分和地址类描述，本地 SEO 排名与门店竞品监控。
• 分析商业搜索意图：结合 shopping、hotels_pack、价格、评分及广告，识别高交易意图并优化落地页与投放策略。