排名关键词查询 API

用 Bearer Key 调用 POST /v1/seo/ranked-keywords，返回结构化 JSON——明确的错误语义，附五种语言的示例代码。

单一 REST 端点
简洁的认证方式
结构化 JSON 响应
可预期的错误语义
游标分页
幂等重试

请求示例

curl -X POST "https://api.agentbody.io/v1/seo/ranked-keywords" \
  -H "Authorization: Bearer <YOUR_AGENTBODY_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"filters":"YOUR_FILTERS","historical_serp_mode":"live","ignore_synonyms":"true","language_code":"YOUR_LANGUAGE_CODE","language_name":"YOUR_LANGUAGE_NAME","limit":"1","load_rank_absolute":"true","location_code":"1","location_name":"YOUR_LOCATION_NAME","offset":"1","order_by":"YOUR_ORDER_BY","tag":"YOUR_TAG","target":"YOUR_TARGET"}'

响应示例

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

Organic ranked keywords.

{
  "items": [],
  "items_count": 0,
  "target": "example_value",
  "total_count": 0
}

功能特点

排名关键词查询 API 端点的技术特性与集成方式。

单一 REST 端点

带 Bearer API Key 调用 POST /v1/seo/ranked-keywords。排名关键词查询 API 返回文档化的 JSON——无需 SDK，任何 HTTP 客户端都可用。

简洁的认证方式

Key 以 Bearer Token 传入。务必保存在服务端：Key 不应出现在浏览器代码、公开仓库或客户端包里。

结构化 JSON 响应

响应字段名稳定且有文档，解析器、表格与 Agent 管道可以直接消费，无需额外清洗。

可预期的错误语义

400 类表示修正请求；401 表示检查 Key；429 表示需降速。临时性 5xx 可安全地退避重试。

游标分页

列表型响应包含 next_cursor 与 has_more。把 cursor 原样传回即可获取下一页——不要手工构造或修改游标。

幂等重试

请求附带幂等 Key 后，重复请求会重放已存储的响应，而不是重复执行与计费。

使用步骤

六步集成排名关键词查询 API：建 Key、发请求、解析、处理错误、分页、监控。

创建 API Key

构造请求

发送 POST /v1/seo/ranked-keywords，带上必填输入（target）。本页示例展示了五种语言下的完整调用。

解析响应

把文档化的 JSON 字段读入你的应用，只存储产品需要的部分。

显式处理错误

修正输入解决 400，轮换 Key 解决 401，5xx 用指数退避重试。校验类失败是最终答案，不是临时故障。

用游标翻页

has_more 为 true 时，把 next_cursor 原样传给下一次请求，直到覆盖所需范围。

监控用量

在控制台跟踪调用与额度。用量端点让你的看板实时反映消耗。

常见问题

什么是排名关键词查询 API？

一个经过认证的 REST 端点（POST /v1/seo/ranked-keywords），返回结构化 JSON。一个 AgentBody Key 同时覆盖它和所有其他端点。

排名关键词查询 API 如何认证？

在 Authorization: Bearer 头中传入 API Key。Key 在控制台创建与轮换，且只保存在服务端。

排名关键词查询 API 的响应长什么样？

成功调用返回字段名稳定且有文档的 JSON。完整的请求与响应示例见本页及链接的文档。

排名关键词查询 API 怎么计费？

每次调用消耗账号额度。价格由网关统一管理并在控制台展示——本页从不写死数字，控制台始终是权威来源。

排名关键词查询 API 支持分页吗？

列表端点返回 next_cursor 与 has_more，把 cursor 原样传回即可继续。详情端点返回单个对象，无分页。

Agent 可以直接调用这个 API 吗？

可以。在 Agent 标签页用一键安装接入官方 AgentBody 技能，你的 Agent 即可用同一个 Key 调用此端点及所有其他 AgentBody 端点。