AgentBodyAgentBody
登录

SERP API

一次带鉴权的 POST 返回关键词的实时结构化 Google SERP 结果——排名、标题、URL 和类型——支持设备、地区和语言参数。

  • 单一 REST 端点
  • 精确市场定向
  • 设备与浏览器保真
  • 结构化结果条目
  • 幂等的计费写入
  • 可预期的错误码
工具API

请求示例

查看 API 文档 完整 API 文档 
curl -X POST "https://api.agentbody.io/v1/seo/google-serp" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"browser_screen_density":"1","browser_screen_height":"1","browser_screen_resolution":"YOUR_BROWSER_SCREEN_RESOLUTION","browser_screen_width":"1","calculate_rectangles":"true","depth":"1","device":"desktop","keyword":"YOUR_KEYWORD","language_code":"YOUR_LANGUAGE_CODE","language_name":"YOUR_LANGUAGE_NAME","load_async_ai_overview":"true","location_code":"1","location_coordinate":"YOUR_LOCATION_COORDINATE","location_name":"YOUR_LOCATION_NAME","os":"windows","se_domain":"YOUR_SE_DOMAIN","search_param":"YOUR_SEARCH_PARAM"}'

响应示例

来自 OpenAPI 规范的已文档化响应。

Organic search results.

{
  "items": [],
  "items_count": 0,
  "keyword": "example_value"
}

功能特点

用 SERP API 按关键词拉取实时结构化 Google 结果——支持设备、地区、语言和域名参数——服务于排名追踪器、SEO 工具和数据管线。

单一 REST 端点

带 bearer API 密钥和关键词调用 POST /v1/seo/google-serp。SERP API 实时执行搜索并以结构化 JSON 返回结果页，你的应用无需托管浏览器、轮换代理或维护解析器就能拿到排名。

精确市场定向

用 location_name、location_code 或 location_coordinate 加语言和 Google se_domain，把每个请求锚定到一个市场。排名随地域和语言变化；这些参数让每个请求对你产品追踪的市场都可复现。

设备与浏览器保真

把 device 设为桌面或移动，可选搜索执行时的浏览器屏幕尺寸。SERP 布局和特型覆盖随设备类别不同——API 暴露这些旋钮，让数据匹配用户真实的搜索方式。

结构化结果条目

收到带排名、标题、URL 和结果类型的有序条目，另有 depth、calculate_rectangles 等更深层解析控制。Schema 为存储而生：条目可直接落进排名追踪表或分析管线。

幂等的计费写入

实时 SERP 请求是按量计费操作。重试时带 Idempotency-Key 头，中断的响应就不会变成双重计费的搜索——网关把同键的相同重复请求视为一次。

可预期的错误码

用文档化的状态码处理失败：400 请求无效、401 密钥缺失或错误、402 余额不足、502/503/504 暂时性上游问题。每类对应明确的修复或重试动作。

使用步骤

按以下六步调用 SERP API：创建密钥，用关键词和市场参数构造 POST 请求，处理结构化结果。

01

创建 API 密钥

创建 AgentBody 账号并在控制台生成 API 密钥。把密钥放在服务端环境或受认可的密钥库，以 bearer 令牌发送。绝不把生产密钥放进浏览器代码或客户端包。

02

构造请求体

向 /v1/seo/google-serp 发送 POST，带必填的 keyword 和你选择的选项——device、location、language、se_domain、depth。本页生成的示例展示 curl、JavaScript、Python、Java 和 Go 的确切请求。

03

加幂等键

给每个可能重试的搜索附上 Idempotency-Key 头——超时、断连、worker 重启。对重复的键，网关返回原始响应，而不是再次执行并计费一次相同搜索。

04

密钥留在服务端

从后端、serverless 函数或定时任务调用端点——任何密钥不出浏览器的地方。若终端用户触发核查，请通过你自己的端点代理，让密钥和计额掌控在你手里。

05

解析 JSON 响应

读取带排名、标题、URL 和类型字段的有序条目。存储追踪器需要的字段，给每行打上请求的市场参数标签——第一天起你就有可复现的排名序列。

06

正确处理错误

400 修请求体，401 配好密钥，402 充值余额。502、503、504 带退避并用同一幂等键重试——它们是暂时性上游状况，不是永久失败。

常见问题

这个 SERP API 是什么？

SERP API 是一个带鉴权的 POST 端点 /v1/seo/google-serp，对你的关键词执行实时 Google 搜索，并以结构化 JSON 返回结果页——带排名、标题、URL 和结果类型的有序条目——同时提供设备、地区和语言控制，保证市场级数据准确。

SERP API 的价格怎么算？

每次实时搜索都是消耗账号额度的按量计费操作。用量计价由网关管理，而非本页写死的数字——在控制台查看当前单价，并用幂等键确保重试绝不双重计费。

它和自建 Google SERP 爬虫方案比怎么样？

不用再维护 SERP 爬虫——无头浏览器、代理轮换、验证码处理和随时因布局变化而崩的解析器——而是调用一个文档化的 REST 端点，接收稳定的 JSON 字段。API 吸收了基础设施，并保持契约稳定。

能查特定国家或城市的结果吗？

可以。在请求体里传 location_name、location_code 或 location_coordinate。搜索按该市场执行，返回的排名反映当地搜索者看到的结果——这是本地排名追踪的核心。

支持非 Google.com 域名和其他语言吗？

把 se_domain 设为你市场使用的 Google 域名，用 language_name 或 language_code 指定搜索语言。与地区选项组合，每个请求都锚定到可复现的市场配置。

怎么处理 API 错误？

400 修请求体，401 修 bearer 密钥，402 处理余额。把 502、503、504 当作暂时性上游故障，在同一幂等键下带退避重试。记录状态码，让管线区分坏请求和暂时性问题。