好搜 SERP API：概览

好搜 SERP API 用于获取指定、语言、设备类型和操作系统下的搜索结果。默认返回前 10 条付费、自然及特色搜索结果；可通过 depth 参数扩大返回结果数量。

本接口会尽可能模拟指定的语言、搜索引擎及设备环境，返回任务创建时对应条件下的搜索结果。可在无痕浏览器中访问响应中的 check_url，核验返回数据与搜索页面的一致性。

系统不会纳用户偏好、搜索历史等个性化因素，因此返回的 SERP 数据不个性化搜索结果。

> 好搜搜索结果不受地理位置影响，因此创建任务时无需也不支持设置位置参数。

支持的设备与操作系统

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

设备类型	支持的操作系统
mobile	ios、android
desktop	windows、macos

支持的功能

本接口提供 advanced 和 html 两种数据获取功能。

Advanced 功能

advanced 功能适用于好搜自然搜索结果，可返回指定、搜索引擎和语言对应的自然结果、付费结果及特色结果。

默认返回前 10 条结果。如需获取更多结果，请在 POST 请求任务对象中提高 depth 参数值。

HTML 功能

html 功能返回指定搜索条件对应的原始 SERP HTML 页面，适用于需要自行解析页面结构、提取未结构化模块或留存页面快的场景。

调用方式

本接口支持 Standard（标准）方式 获取数据。该方式需要分别提交 POST 任务请求和 GET 结果请求，但通常更低的调用成本。

标准流程如下：

1. 通过 POST 请求创建一个或多个 SERP 采集任务；
2. 等平台完成任务采集；
3. 获取已完成任务的 ID 列表；
4. 通过 GET 请求获取指定任务的结果。

POST 请求体为 JSON 数组，即使提交一个任务也应使用数组结构：

[
  {
    "keyword": "",
    "language_code": "zh",
    "device": "desktop",
    "os": "windows",
    "depth": 10
  }
]

回调通知

创建任务时，也可以以下回调地址：

参数	说明
pingback_url	任务完成后，平台向该地址发送完成通知。收到通知后，可再请求获取任务结果。
postback_url	任务完成后，平台将任务结果直接推送至该地址。

使用 postback_url 时，还指定数据返回功能类型：

• regular：返回结构化搜索结果；
• html：返回原始 SERP HTML。

如果使用标准方式且未 pingback_url 或 postback_url，可通过 Tasks Ready 接口查询所有已完成但尚未获取结果的任务 ID，再通过 Task GET 接口逐个获取结果。

优级与计费

标准方式支持以下两种任务执行优级：

优级	说明
Normal priority	常规执行优级，适合非实时批量采集任务。
High priority	高执行优级，适合对结果返回速度要求较高的任务。

不同优级的任务执行速度和费用不同。扣费以响应头 X-SeerMarTech-Charge-CNY 为准。

调用限制

平台限流以认证说明中的 30/60/120 次/分钟规则为准；

• 单个 POST 请求最多可 100 个任务；
• 如有更高并发或任务量需求，请联系技术支持调整限额。

测试环境

可使用本平台沙盒环境验证请求参数、任务创建流程和响应结构。沙盒环境适合接口联调与开发测试，正式数据采集请使用生产环境凭证。

实用场景

• 监控排名：按桌面端或移动端持续采集指定的自然排名与付费结果，评估 SEO 排名变化和优化成效。
• 追踪竞品投放：获取搜索结果中的广告与特色展示，识别竞品投放策略及位置。
• 分析移动端与桌面端差异：对比不同设备和操作系统下的 SERP 结果，发现移动优索引、页面适或排名差异问题。
• 构建搜索结果快库：通过 html 功能留存原始搜索结果页面，用于页面结构解析、结果复盘和异常变化审计。
• 批量发现机会：提高 depth 获取更多自然结果，分析排名靠前页面的类型、站点分布与长尾竞争格局。