SEO API
十二个工具为应用或 Agent 提供 SEO 数据:一个关键词有多少人搜、排上去有多难,哪些关键词和页面给域名带来搜索流量,谁在和它竞争,谁在链接它,它的 Domain Rating,以及站点有多少访问量。每个工具都是 /v1/seo/ 下的一个 POST,使用你的 BeatAPI API 密钥,在一次响应里返回结果。Agent 通过能力接口使用同样的工具。
快速开始
认证
每次调用都用 Authorization: Bearer <key> 发送 BeatAPI API 密钥,带不带 sk- 前缀都可以。密钥在控制台 → API Keys 创建。所有工具都在 https://api.beatapi.io 上,从账户余额扣费。
选择工具
Domain Rating 和站点总访问量见 Domain Rating 与站点流量。
没有实时结果页工具。要查域名在某个关键词上的排名,请用 ranked-keywords 加 contains。返回的是最后记录的排名,不是实时排名。
国家和语言
country 和 language 选择市场:该国家、该语言下的 Google 搜索。关键词工具以及 domain-overview、ranked-keywords、top-pages、competitors 接受这两个字段。外链工具没有市场概念,传这两个字段会被拒绝。
不在覆盖范围内的国家或语言会被 400 bad_request 拒绝,错误信息会说明该市场支持哪些语言:language 'de' is not covered in us; use one of: en, es。
limit 和 offset
keyword-ideas、ranked-keywords、top-pages、competitors 和 backlinks 按页返回多行数据。
这些响应会带回 limit 和 offset,已知时还会带 total,即可获取的总行数。
响应
所有工具都同步返回:结果就在 POST 的响应里,无需轮询。大多数调用只要几秒。
usage.price_usd 是结算后的扣费,单位为美元。billing_unit 始终为 request,quantity 始终为 1;billed_rows 说明这笔费用覆盖了多少行。
数据里没有的数字不会出现在行里,使用前请先判断字段是否存在。未知请求字段会被 400 bad_request 拒绝:字段拼错却被悄悄忽略,返回的就是另一个问题的答案。
关键词工具
关键词概览
POST https://api.beatapi.io/v1/seo/keyword-overview
查询已有关键词的搜索量、CPC、竞争度、难度、意图和逐月历史。没人搜索的关键词不会返回,也不会写成零。
响应示例见快速开始。每行的字段:
关键词拓展
POST https://api.beatapi.io/v1/seo/keyword-ideas
根据种子关键词返回相关关键词,最相关的排在前面。每行的字段与 keyword-overview 相同,但没有 monthly_searches。
关键词难度
POST https://api.beatapi.io/v1/seo/keyword-difficulty
一次查询多个关键词,只返回 keyword_difficulty。接受的字段与 keyword-overview 相同。
域名工具
这四个工具都接受 domain(如 example.com),以及 country 和 language。
域名概览
POST https://api.beatapi.io/v1/seo/domain-overview
域名在一个市场里的自然和付费搜索足迹。这里只有搜索流量,不是站点总访问量。
没有记录的域名返回 has_data: false,既没有 organic 也没有 paid。这表示没有数据,不是流量为零,调用照常计费。
排名关键词
POST https://api.beatapi.io/v1/seo/ranked-keywords
域名在一个市场里有排名的关键词,搜索量最高的排在前面。
每行在 keyword-ideas 的字段之外增加:
热门页面
POST https://api.beatapi.io/v1/seo/top-pages
域名下的页面,估算搜索流量最高的排在前面。字段:domain、limit、offset、country、language。每行有 url 和该页面的足迹字段。
竞争对手
POST https://api.beatapi.io/v1/seo/competitors
和某域名竞争相同搜索关键词的域名。字段:domain、limit、offset、country、language。结果里不含该域名自身和最大的综合站点(如 youtube.com、wikipedia.org),total 只统计剩下的部分。
外链工具
外链概况
POST https://api.beatapi.io/v1/seo/backlink-summary
域名的外链情况。唯一的字段是 domain。
域名没有记录时 has_data 为 false,没有其他字段,调用照常计费。
外链列表
POST https://api.beatapi.io/v1/seo/backlinks
指向一个域名的链接,最强的排在前面。
如何解读数字
- 搜索流量。
search_traffic_estimate是估算的搜索流量,不是站点总访问量。 - 都是估算。 流量和价值数字都是估算,不是对站点的实测。
- Link authority。
link_authority取值 0 到 1000,是本数据集自己的刻度。 - 关键词难度是本数据集自己的刻度,不要和其他工具的分数比较。
- 缺失不等于零。 缺失的数字表示未知,绝不等于零。
- 没有实时结果页。 没有实时结果页工具。要查域名在某个关键词上的排名,请用
ranked-keywords加contains。返回的是最后记录的排名,不是实时排名。 - Domain Rating 和站点流量的说明单独放在如何解读这些数字。
计费
Domain Rating 和站点流量有单独的价格。
domain-overview和backlink-summary返回一条记录,算作一行;has_data为false时不算行。返回 100 行的ranked-keywords调用费用是 $0.048。- 什么都没找到的调用仍收按次部分。被拒绝的请求(
400)不收费,失败的调用(503)也不收费。 - 调用开始前,余额必须够付这次调用可能的最高费用:
limit的全部行数,或发送的全部关键词。之后只按实际返回的内容收费。 - 客户端可能重试同一请求时,请发送
Idempotency-Key请求头。同一个键配不同的请求体会被409 idempotency_conflict拒绝。
Agent
SEO 数据没有单独的 MCP 工具。在 BeatAPI MCP 端点 https://beatapi.io/mcp 上,Agent 用 capabilities_search、capabilities_inspect 和 capabilities_run 配合下面的引用来调用:
Domain Rating 和站点流量的引用和这些工具列在一起。
Inspect 会显示输入结构和当前价格。input 就是该工具的请求体,Run 直接返回结果:
同样的三个调用也可以走 REST:POST /v1/capabilities/search、/v1/capabilities/inspect 和 /v1/capabilities/run。详见能力接口。
错误
错误使用 BeatAPI 标准错误结构,每个错误都带 retryable。重试策略见错误说明。
503 绝不收费。BeatAPI 不返回 502。
Domain Rating 与站点流量
另外三个工具的用法相同:同样的密钥,同样在响应里返回结果,同样的 usage 和错误。它们接受 domain,没有市场概念,因此 country 和 language 会被拒绝。也没有 limit 或 offset。
Domain Rating
POST https://api.beatapi.io/v1/seo/domain-rating
domain_rating 取值 0 到 100。link_rank 是域名按链接计算的全球排名,数值越低越强。
Domain Rating 历史
POST https://api.beatapi.io/v1/seo/domain-rating-history
未知域名返回 has_data: false、空的 results 和 billed_rows: 1。
站点流量
POST https://api.beatapi.io/v1/seo/site-traffic
网站来自所有渠道的估算总访问量,以及来源、国家、排名和参与度。
如何解读这些数字
- 两种流量。
search_traffic_estimate是估算的搜索流量;site_visits_estimate是来自所有渠道的总访问量。两者是不同的度量,绝不要相加或比较。访问量不是独立访客数。 - 两种权威分。
link_authority取值 0 到 1000,是本数据集自己的刻度;domain_rating取值 0 到 100。两者不能互相换算。 - 没有记录。
has_data: false表示该域名没有记录,这和评分或流量为零不同:新站点的评分可以是0,同时仍有link_rank。
这些工具的价格
has_data为false时,domain-rating和site-traffic照常计费。domain-rating-history查询未知域名时不返回月份,按一个月收费,即 $0.004。- 被拒绝的请求(
400)和失败的调用(503)不收费。 domain-rating-history运行前,余额必须够付 24 个月的历史。之后只按实际返回的内容收费。

