Yahoo SERP API 概览

Yahoo SERP API 用于获取 Yahoo 搜索结果页（SERP）数据。主要容接口路径：/v3/serp/yahoo/organic/task_post/、/v3/serp/yahoo/organic/task_get/regular/、/v3/serp/yahoo/organic/live/regular/、/v3/serp/yahoo/organic/live/advanced/ 和 /v3/serp/yahoo/organic/live/html/。

本接口基于 Yahoo Organic 搜索引擎返回搜索结果。结果会根据提交任务时指定的、语言和地区参数生成，并尽可能模拟目标地区的搜索环境。可通过响应中的 check_url 使用浏览器无痕模式访问对应结果页，以核验返回数据。

> 注意：本接口不会模拟用户个人偏好、搜索历史记录及个性化因素，因此返回结果不个性化排序影响。

设备与操作系统

创建任务时，可指定以下设备类型及操作系统：

设备类型	支持的操作系统
移动端（mobile）	iOS、Android
桌面端（desktop）	Windows、macOS

排名字段说明

Yahoo SERP 结果使用以下字段描述排名位置：

字段	说明
rank_group	结果在所属分组的排名。例如，自然搜索结果组、图片组或 SERP素组的位置。
rank_absolute	结果在整个搜索结果页中的绝对位置。

rank_group 适合分析同类结果中的竞争排名，rank_absolute 适合评估结果在完整 SERP 页面中的展示位置。

SERP 数据功能

本接口提供 Regular、Advanced 和 HTML 三种数据获取功能。

Regular：常规搜索结果

接口路径：/v3/serp/yahoo/organic/live/regular/

Regular 功能最多返回指定、搜索地区和语言条件下的 100 条自然搜索结果。

该功能适用于需自然排名、标题、链接、描述等基础结果数据的场景。它不提供 SERP 特殊的完整信息；如需获取精选摘要及扩展 SERP素，请使用 Advanced 功能。

Advanced：完整 SERP 结果

接口路径：/v3/serp/yahoo/organic/live/advanced/

Advanced 功能返回指定、搜索地区和语言条件下排名靠前的 10 条搜索结果，并提供更完整的 SERP 页面信息。

适用于需要分析精选摘要、扩展搜索模块及非自然结果的业务场景。

HTML：原始页面源码

接口路径：/v3/serp/yahoo/organic/live/html/

HTML 功能返回指定、搜索地区和语言条件下的原始 SERP HTML 页面。

适用于需要自行解析页面结构、保存原始搜索页面快或提取未结构化的场景。

数据获取方式

本接口支持 Standard 和 Live 两种结果交付方式。

Live 实时方式

Live 方式在请求后实时返回结果，适用于需要即时获取搜索结果的业务。

常用接口：

• /v3/serp/yahoo/organic/live/regular/
• /v3/serp/yahoo/organic/live/advanced/
• /v3/serp/yahoo/organic/live/html/

Live 方式无需分别调用任务创建和任务获取接口，但相较于 Standard 方式费用更高。

Standard 异步方式

Standard 方式适用于不要求实时返回结果的批量采集任务，通常成本更低。

型调用流程如下：

1. 通过 POST /v3/serp/yahoo/organic/task_post/ 创建任务；
2. 等平台完成数据采集；
3. 通过 GET /v3/serp/yahoo/organic/task_get/regular/ 等任务获取接口读取结果。

如果一次创建多个任务，可按以下方式批量处理：

1. 调用 /v3/serp/yahoo/organic/tasks_ready/ 获取已完成任务的 id 列表；
2. 针对每个任务 id，调用对应的 Task GET 接口获取结果。

回调通知

创建 Standard 任务时，可使用以下字段接收任务完成通知：

字段	说明
pingback_url	任务完成后向指定地址发送完成通知。收到通知后，您可再调用 Task GET 接口获取结果。
postback_url	任务完成后，将结果直接推送到指定地址。使用该字段时，还指定数据获取功能类型：regular 或 html。

优级与计费

Live 方式实时返回结果，因此通常最高的请求成本。

Standard 方式支持以下两种执行优级：

1. 普通优级（Normal）：适用于对返回时效要求较低的任务。
2. 高优级（High）：适用于需要更快完成采集的任务。

任务费用还会受到 depth 参数影响。

> 注意：当 depth过默认值时，任务费用会增加。若默认深度为 10，则每增加 10 条结果通常按一个额外结果深度单位计费。

扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

请求频率限制

Yahoo SERP 接口默认支持以下调用限制：

限制项	默认限制
平台限流以认证说明中的 30/60/120 次/分钟规则为准
单次 POST 请求中的任务数	最多 100 个任务

对于高并发或大规模批量采集场景，建议控制请求速率、按批次提交任务，并结合 tasks_ready 接口和回调机制减少无效轮询。

实用场景

• 监控自然排名：定期查询目标的 Yahoo 自然搜索结果，识别网站排名变化并评估 SEO 优化效果。
• 分析本地化搜索可见性：按不同语言、地区、设备和操作系统提交任务，比较品牌或页面在目标市场中的展示差异。
• 追踪竞品搜索表现：采集竞品域名在核心下的排名、标题和摘要信息，为策略与布局提供依据。
• 识别 SERP 特殊机会：使用 Advanced 功能检测精选摘要等扩展，评估高位置的优化机会。
• 归档搜索页面证据：使用 HTML 功能保存指定时间和地区下的原始搜索结果页，用于页面结构分析、审计或异常排查。