Skip to content

Yahoo 实时高级搜索结果 API

接口概述

本接口用于实时获取 Yahoo 搜索结果页(SERP)的高级结构化数据,适合需要直接消费搜索结果的场景,例如自然结果、广告、图片、视频、搜索、本地、精选摘要等。

接口返回结果会根据你指定的地区语言生成。地区和语言可分别通过以下容接口获取:

  • 地区列表:/v3/serp/wp/locations
  • 语言列表:/v3/serp/wp/languages

请求方式

POST https://api.seermartech.cn/v3/serp/wp/organic/live/advanced

说明:文档标题对应 Yahoo 场景,但参考文档中的路径示例同时出现了 wpv2 容写法。接时,请以你的容路由为准;本文保留所有 /v3/... 技术路径写法以便容接口体系。

计费说明

该接口按请求计费。

  • 每次请求都会产生费用
  • 单次任务支持提交 1 个 task
  • 频率限制:最高 2000 次 API 调用/分钟
  • 实扣费以响应头 X-SeerMarTech-Charge-CNY 为准

抓取深度计费:

  • depth 默认值为 6
  • depth 最大值为 700
  • Yahoo 单个 SERP 页面返回结果可能少于 10 条,因此将 depth 设为高于默认值时,可能触发额外 SERP 页抓取并增加费用
  • 参考价无法从原文精确换算到固定单次价格,扣费以响应头 X-SeerMarTech-Charge-CNY 为准

请求体格式

所有 POST 数据使用 JSON(UTF-8) 提交,请求体格式为 JSON 数组

json
[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

请求参数

以下为设置任务时可用的字段说明。

字段名类型说明
urlstring搜索查询的直接 URL。可选。你可以直接传搜索结果页 URL,由本接口自动解析为所需参数。但这种方式处理复杂,且要求 URL 中已准确语言与地区信息,通常不建议使用。示例:https://search.yahoo.com/search?p=rank+checker&n=100&vl=lang_en&vc=us&ei=UTF-8
keywordstring。最大长度 700 个字符。所有 %## 会被解码,+ 会被解码为空格。如果中需要保留 %,请写为 %25;如果需要保留 +,请写为 %2B
location_namestring搜索地区名。当未指定 location_codelocation_coordinate 时填。使用该字段时,无需再传 location_codelocation_coordinate。示例:London,England,United Kingdom
location_codeinteger搜索地区编码。当未指定 location_namelocation_coordinate 时填。使用该字段时,无需再传 location_namelocation_coordinate。示例:2840
location_coordinatestring地理坐标位置。当未指定 location_namelocation_code 时填。格式为 latitude,longitude,radiuslatitudelongitude 最多 7 位小数;radius 最小值 199.9(毫米),最大值 199999(毫米)。示例:53.476225,-2.243572,200
language_namestring搜索语言名。当未指定 language_code 时填。使用该字段时,无需再传 language_code。示例:English
language_codestring搜索语言编码。当未指定 language_name 时填。使用该字段时,无需再传 language_name。示例:en
devicestring设备类型。可选。可选值:desktopmobile。默认:desktop
osstring设备操作系统。可选。当 device=desktop 时,可选 windowsmacos,默认 windows;当 device=mobile 时,可选 androidios,默认 android
se_domainstring搜索引擎域名。可选。系统会根据地区和语言自动选择合适域名,你也可以手动指定。示例:au.search.yahoo.comuk.search.yahoo.comca.search.yahoo.com
depthinteger解析深度,即希望返回的 SERP 结果数量。可选。默认 6,最大 700。账号会按抓取到的 SERP 页面计费,较高深度可能带来更高费用。
max_crawl_pagesinteger最大抓取页数。可选。默认 1,最大 100。该参数与 depth合使用:depth 决定需要多少结果,max_crawl_pages 决定最多抓取多少页。
targetstring指定要筛选的目标域名、子域名或页面。可选。域名或子域名不要 https://www.。只会返回 url 字段的 SERP素。支持使用通符 * 缩小匹范围。示例:example.comexample.com**example.com**example.comexample.com/example-pageexample.com/example-page*
search_paramstring附加搜索参数。可选。用于传递 Yahoo 查询附加参数。
stop_crawl_on_matcharray命中目标后停止继续抓取。可选。为目标对象数组,每个对象 match_typematch_value。最多支持 10 个目标对象。如果设置该参数,响应将返回直到命中指定目标为止的 SERP 结果;在命中条件之前抓取的所有 SERP 页面都会计费。
tagstring自定义任务标识。可选。最大长度 255 字符。可用于请求与结果之间的业务,响应 data 中会原样返回。

stop_crawl_on_match 子字段

字段名类型说明
match_valuestring当指定 stop_crawl_on_match 时填。目标域名、子域名或通符表达式。域名/子域名不要协议头。示例:"本平台.com""/blog/post-*"
match_typestring当指定 stop_crawl_on_match 时填。匹类型,可选值:domain(精确域名或子域名)、with_subdomains(主域名及子域名)、wildcard(通符模式)

请求示例

cURL

bash
curl --location --request POST "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced" \
--header "Authorization: Bearer smt_live_YOUR_KEY" \
--header "Content-Type: application/json" \
--data-raw '[
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]'

Python

python
import requests

url = "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced"
headers = {
 "Authorization": "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
}
data = [
 {
 "language_code": "en",
 "location_code": 2840,
 "keyword": "albert einstein"
 }
]

response = requests.post(url, headers=headers, json=data)
print(response.json)

TypeScript

typescript
import axios from "axios";

async function main {
 const response = await axios.post(
 "https://api.seermartech.cn/v3/serp/wp/v2/live/advanced",
 [
 {
 language_code: "en",
 location_code: 2840,
 keyword: "albert einstein"
 }
 ],
 {
 headers: {
 Authorization: "Bearer smt_live_YOUR_KEY",
 "Content-Type": "application/json"
 }
 }
 );

 // 输出接口返回结果
 console.log(response.data);
}

main.catch(console.error);

响应结构

接口返回 JSON 编码数据,顶层 tasks 数组。

顶层字段

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

tasks[] 字段

字段名类型说明
idstring任务唯一标识,UUID 格式
status_codeinteger任务状态码,范围通常为 10000 - 60000
status_messagestring任务状态说明
timestring任务执行耗时
costfloat当前任务费用,单位 USD
result_countintegerresult 数组数
patharrayURL 路径
dataobject与请求中提交参数一致的回显数据
resultarray搜索结果数组

result[] 通用字段

字段名类型说明
keywordstring请求中的。返回时 %## 会被解码,+ 会被解码为空格
typestring请求中的搜索引擎类型
se_domainstring请求中的搜索引擎域名
location_codeinteger请求中的地区编码
language_codestring请求中的语言编码
check_urlstring搜索结果直达 URL,可用于人工核验结果准确性
datetimestring结果获取时间,UTC 格式:yyyy-mm-dd hh-mm-ss +00:00
spellobject搜索引擎自动纠错信息
refinement_chipsobject搜索细化标签;此接口中通常为 null
item_typesarray当前 SERP 中出现的结果类型列表
se_results_countintegerSERP 总结果数
pages_countinteger实抓取的结果页数
items_countintegeritems 数组中的数量
itemsarray解析后的 SERP素数组

spell 字段

字段名类型说明
keywordstring搜索引擎纠正后的
typestring纠错类型,可选值:did_you_meanshowing_results_forno_results_found_forincluding_results_for

items 结果类型说明

item_types / items[].type 可能出现以下类型:

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

下面列出各类 SERP素的核心字段。


organic 自然结果

字段名类型说明
typestring固定为 organic
rank_groupinteger同类型结果组排名
rank_absoluteinteger在整个 SERP 中的绝对排名
pageinteger所在搜索结果页码
positionstring页面位置,leftright
xpathstring素 XPath
domainstring结果域名
titlestring标题
urlstring结果 URL
cache_urlstring缓存页面 URL
related_search_urlstring站点搜索 URL
breadcrumbstring面屑
is_imageboolean是否图片
is_videoboolean是否视频
is_featured_snippetboolean是否为精选摘要结果
is_maliciousboolean是否被标记为恶意页面
is_web_storyboolean是否为 Web Story
descriptionstring描述摘要
pre_snippetstring描述前附加信息
extended_snippetstring描述后附加信息
imagesarray结果图片
amp_versionboolean是否有 AMP 页面
ratingobject评分信息
priceobject价格信息
highlightedarray描述中加粗的
linksarray站点链接(sitelinks)
faqobjectFAQ 扩展
extended_people_also_searcharray返回搜索页后触发的扩展搜索
about_this_resultobject“此结果”信息;Yahoo 中始终为 null
related_resultarray同域结果;Yahoo 中始终为 null
rectangleobject结果在页面中的矩形位置信息;Yahoo 当前始终为 null

organic 子对象

images[]

字段名类型说明
typestring固定为 images_element
altstring图片 alt 文本
urlstring对应页面 URL
image_urlstring图片 URL

rating

字段名类型说明
rating_typestring评分类型:Max5PercentsCustomMax
valuefloat评分值
votes_countinteger评价数
rating_maxinteger评分上限

price

字段名类型说明
currentfloat当前价格
regularfloat原价
max_valuefloat最高价格
currencystring货币 ISO 代码
is_price_rangeboolean是否为价格区间
displayed_pricestring原始展示价格文本
字段名类型说明
typestring固定为 link_element
titlestring链接标题
descriptionstring链接描述
urlstring链接 URL

faq

字段名类型说明
typestring固定为 faq_box
itemsarrayFAQ 列表

faq.items[]

字段名类型说明
typestring固定为 faq_box_element
titlestring问题
descriptionstring答案
linksarrayFAQ链接

字段名类型说明
typestring固定为 paid
rank_groupinteger同类型组排名
rank_absoluteintegerSERP 绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
domainstring广告域名
descriptionstring描述
titlestring标题
urlstring广告目标 URL
breadcrumbstring面屑
highlightedarray加粗词
extraobject额外信息
description_rowsarray扩展描述
linksarray广告附加链接
priceobject价格信息
rectangleobject矩形信息;Yahoo 当前始终为 null

extra

字段名类型说明
ad_aclkstring广告标识符

images 图片结果块

字段名类型说明
typestring固定为 images
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
titlestring模块标题
urlstring图片搜索页 URL
itemsarray图片项列表
related_image_searchesarray图片搜索建议
rectangleobject矩形信息;Yahoo 当前始终为 null

images.items[]

字段名类型说明
typestring固定为 images_element
altstring图片 alt
urlstring原始图片链接页
image_urlstring压缩图 URL
字段名类型说明
typestring固定为 related_image_searches_element
titlestring搜索
altstring图 alt
urlstring原始图片页
image_urlstring压缩图片 URL

video 视频结果块

字段名类型说明
typestring固定为 video
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
itemsarray视频列表
rectangleobject矩形信息;Yahoo 当前始终为 null

video.items[]

字段名类型说明
typestring固定为 video_element
sourcestring视频来源
titlestring标题
timestampstring发布时间,UTC 格式
urlstring视频 URL

shopping 购物结果块

字段名类型说明
typestring固定为 shopping
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
titlestring模块标题
itemsarray商品列表
rectangleobject矩形信息;Yahoo 当前始终为 null

shopping.items[]

字段名类型说明
typestring固定为 shopping_element
titlestring商品标题
priceobject价格信息
sourcestring信息来源
descriptionstring描述
marketplacestring商家聚合平台
marketplace_urlstring聚合平台 URL
urlstring商品 URL

字段名类型说明
typestring固定为 featured_snippet
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
domainstring来源域名
titlestring结果标题
featured_titlestring摘要来源页标题
descriptionstring摘要描述
timestampstring发布时间,UTC 格式
urlstring来源 URL
imagesarray图片列表
tableobject表格结构
rectangleobject矩形信息;Yahoo 当前始终为 null

table

字段名类型说明
table_headerarray列名
table_contentarray表格,每个表示一行

top_stories 热门新闻

字段名类型说明
typestring固定为 top_stories
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
itemsarray新闻列表
rectangleobject矩形信息;Yahoo 当前始终为 null

top_stories.items[]

字段名类型说明
typestring固定为 top_stories_element
sourcestring来源名称
domainstring来源域名
titlestring标题
datestring发布日期
amp_versionboolean是否为 AMP 页面
timestampstring发布时间,UTC 格式
urlstring页面 URL
image_urlstring图片 URL

hotels_pack店结果块

字段名类型说明
typestring固定为 hotels_pack
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
titlestring模块标题
date_fromstring住日期,格式 yyyy-mm-dd
date_tostring离店日期,格式 yyyy-mm-dd
itemsarray店结果列表
rectangleobject矩形信息;Yahoo 当前始终为 null

hotels_pack.items[]

字段名类型说明
typestring固定为 hotels_pack_element
priceobject指定日期的预订价格
titlestring店/住宿名称
desriptionstring描述文本
hotel_identifierstring店唯一标识
domainstring域名
urlstringURL
is_paidboolean是否为广告
ratingobject评分信息

local_pack 本地结果

字段名类型说明
typestring固定为 local_pack
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
titlestring商家名称
descriptionstring商家摘要
domainstring域名
phonestring电话
urlstring页面 URL
is_paidboolean是否广告
ratingobject评分信息
cidstring本地商户唯一 ID
rectangleobject矩形信息;Yahoo 当前始终为 null

recipes 菜谱结果块

字段名类型说明
typestring固定为 recipes
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
itemsarray菜谱项列表
rectangleobject矩形信息;Yahoo 当前始终为 null

recipes.items[]

字段名类型说明
typestring固定为 recipes_element
titlestring标题
urlstring菜谱 URL
domainstring域名
sourcestring来源
descriptionstring摘要
timestring烹饪/准备总时长
ratingobject评分信息

people_also_ask 问题

字段名类型说明
typestring固定为 people_also_ask
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
itemsarray问题列表
rectangleobject矩形信息;Yahoo 当前始终为 null

people_also_ask.items[]

字段名类型说明
typestring固定为 people_also_ask_element
titlestring问题标题
xpathstring素 XPath
expanded_elementarray展开后的答案

expanded_element[]

字段名类型说明
typestring固定为 people_also_ask_expanded_element
featured_titlestring展开标题
urlstring来源 URL
domainstring来源域名
titlestring结果标题
descriptionstring描述
timestampstring发布时间,UTC 格式
tableobject表格信息

字段名类型说明
typestring固定为 related_searches
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
itemsarray搜索项
rectangleobject矩形信息;Yahoo 当前始终为 null

ai_overview AI 概览

字段名类型说明
typestring固定为 ai_overview
rank_groupinteger同类型组排名
rank_absoluteinteger绝对排名
pageinteger页码
positionstringleftright
xpathstring素 XPath
asynchronous_ai_overviewboolean是否异步加载;true 表示异步加载,false 表示来自缓存
markdownstringMarkdown 格式
itemsarrayAI 概览条目
referencesarray引用来源列表
rectangleobject矩形参数;在请求中启用能力时返回,否则为 null

注意:原文说明当前 Yahoo Organic SERP API 中,ai_overview 的暂不可用。

ai_overview.items[]

字段名类型说明
typestring固定为 ai_overview_element
positionstringleftright
titlestring条目标题
textstring条目文本
markdownstringMarkdown

ai_overview.references[]

字段名类型说明
typestring固定为 ai_overview_reference
sourcestring引用来源名或标题
domainstring引用域名
urlstring引用页面 URL
titlestring引用页面标题
textstring用于生成 AI 概览的引用摘要文本

错误处理

建议对以下层级分别进行状态判断:

  1. 顶层 status_code
  2. tasks[].status_code
  3. 业务结果是否为空,例如 result_count=0items_count=0

常见原则:

  • 20000:请求成功
  • 状态码:表示参数错误、认证失败、额限制或数据抓取异常等

错误码请参考你接环境中的 /v3/appendix/errors 容错误码定义。生产环境中应建立完善的异常重试、时控制和空结果底机制。

响应示例

以下为整理后的示例响应片段,展示主要结构:

json
{
 "version": "0.1.20220414",
 "status_code": 20000,
 "status_message": "Ok.",
 "time": "0.1721 sec.",
 "cost": 0,
 "tasks_count": 1,
 "tasks_error": 0,
 "tasks": [
 {
 "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"
 },
 "result": [
 {
 "se_results_count": 0,
 "pages_count": 1,
 "items_count": 137,
 "items": [
 {
 "type": "featured_snippet",
 "rank_group": 1,
 "rank_absolute": 1,
 "page": 1,
 "position": "left",
 "domain": "www.youtube.com",
 "title": "8 KNOTS You Need to Know - How to tie knots that you will",
 "description": "8 KNOTS You Need to Know - How to tie knots that you will actually use.",
 "url": "https://www.youtube.com/watch?v=0yfFo0-1u1M",
 "rectangle": null
 },
 {
 "type": "organic",
 "rank_group": 1,
 "rank_absolute": 6,
 "page": 1,
 "position": "left",
 "domain": "www.expedia.com",
 "title": "Top New York Hotels from $127 (FREE cancellation on select ...",
 "url": "https://www.expedia.com/New-York-Hotels.d178293.Travel-Guide-Hotels/",
 "breadcrumb": "www.expedia.com > New York Vacation Packages",
 "is_image": false,
 "is_video": false,
 "description": "Book your hotel in New York and pay later with Expedia.",
 "amp_version": false,
 "rectangle": null
 },
 {
 "type": "images",
 "rank_group": 1,
 "rank_absolute": 13,
 "page": 2,
 "position": "left",
 "title": "Images",
 "url": "https://images.search.yahoo.com/search/images?p=hotels+in+New+York",
 "items": [],
 "rectangle": null
 },
 {
 "type": "local_pack",
 "rank_group": 1,
 "rank_absolute": 4,
 "page": 1,
 "position": "left",
 "title": "PizzArte",
 "domain": "slicelife.com",
 "phone": "(212) 247-3936",
 "url": "https://slicelife.com/restaurants/ny/new-york/10019/pizzarte/menu",
 "is_paid": false,
 "cid": "99660059",
 "rectangle": null
 }
 ]
 }
 ]
 }
 ]
}

使用建议

  • 若你只心某个域名是否结果页,优使用 target,可减少后处理逻辑
  • 若你希望在目标出现后立即停止抓取,使用 stop_crawl_on_match
  • 若你需要更完整的结果覆盖率,结合 depthmax_crawl_pages 一起控制
  • 若你的业务对地域敏感,优使用 location_codelocation_coordinate,名称歧义
  • 若你要核验结果真实性,可使用返回中的 check_url

实用场景

  • 监控排名:按国家、语言、设备拉取 Yahoo 实时 SERP,持续跟踪品牌词、品类词和竞品词的自然排名变化。
  • 识别 SERP 版位机会:解析 featured_snippetpeople_also_askimagesvideo 等模块,帮助团队判断该适合做哪类资产。
  • 筛选竞品页面:结合 targetstop_crawl_on_match,快速定位指定域名在搜索结果中的出现位置,评估竞品流量。
  • 分析本地搜索格局:利用 local_pack 结果采集本地商户名称、电话、域名与排名,支持门店 SEO 与区域市场研究。
  • 监测广告与自然结果分布:同时获取 paidorganic素,评估某类的商业化程度,投放与自然流量策略制定。

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