> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# SEO API

> 用一把 BeatAPI 密钥查询关键词数据、域名排名、外链、Domain Rating 和站点流量——十二个工具都在响应里直接返回结果，应用和 Agent 都能用。

十二个工具为应用或 Agent 提供 SEO 数据：一个关键词有多少人搜、排上去有多难，哪些关键词和页面给域名带来搜索流量，谁在和它竞争，谁在链接它，它的 Domain Rating，以及站点有多少访问量。每个工具都是 `/v1/seo/` 下的一个 `POST`，使用你的 BeatAPI API 密钥，在一次响应里返回结果。Agent 通过[能力接口](#agents)使用同样的工具。

## 快速开始

```bash
curl https://api.beatapi.io/v1/seo/keyword-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis cluster"],"country":"us"}'
```

```json
{
  "object": "seo.keyword_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "monthly_searches": [{ "year": 2026, "month": 9, "search_volume": 590 }]
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

## 认证

每次调用都用 `Authorization: Bearer <key>` 发送 BeatAPI API 密钥，带不带 `sk-` 前缀都可以。密钥在[控制台 → API Keys](https://beatapi.io/dashboard/apikeys) 创建。所有工具都在 `https://api.beatapi.io` 上，从账户余额扣费。

## 选择工具

| 你想要                      | 工具                   |
| ------------------------ | -------------------- |
| 已有关键词的搜索量、CPC、难度、意图和逐月历史 | `keyword-overview`   |
| 围绕某个主题的新关键词              | `keyword-ideas`      |
| 只要一批关键词的难度               | `keyword-difficulty` |
| 域名在一个市场里的搜索足迹            | `domain-overview`    |
| 域名有排名的关键词，或它在某个关键词上的排名   | `ranked-keywords`    |
| 域名下按搜索流量排序的页面            | `top-pages`          |
| 竞争相同关键词的域名               | `competitors`        |
| 域名外链情况的汇总数字              | `backlink-summary`   |
| 外链本身                     | `backlinks`          |

Domain Rating 和站点总访问量见 [Domain Rating 与站点流量](#domain-rating-and-site-traffic)。

没有实时结果页工具。要查域名在某个关键词上的排名，请用 `ranked-keywords` 加 `contains`。返回的是最后记录的排名，不是实时排名。

## 国家和语言

`country` 和 `language` 选择市场：该国家、该语言下的 Google 搜索。关键词工具以及 `domain-overview`、`ranked-keywords`、`top-pages`、`competitors` 接受这两个字段。外链工具没有市场概念，传这两个字段会被拒绝。

| 字段         | 默认值      | 规则                                                      |
| ---------- | -------- | ------------------------------------------------------- |
| `country`  | `us`     | 两位小写代码，如 `us`、`gb`、`de` 或 `jp`。覆盖约 90 个市场，不含中国（`cn`）。   |
| `language` | 该市场的主要语言 | 必须是该市场的语言之一，如 `us` 的 `es`、`ca` 的 `fr` 或 `hk` 的 `zh-TW`。 |

不在覆盖范围内的国家或语言会被 `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`  | `100` | 1–1000 行，`competitors` 为 1–999 行。每返回一行都计费，需要多少就取多少。 |
| `offset` | `0`   | 跳过 0–10000 行。要下一页，就在此值上加 `limit`。                   |

这些响应会带回 `limit` 和 `offset`，已知时还会带 `total`，即可获取的总行数。

## 响应

所有工具都同步返回：结果就在 `POST` 的响应里，无需轮询。大多数调用只要几秒。

| 字段                   | 说明                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------- |
| `object`             | 工具名称，如 `seo.ranked_keywords`。                                                         |
| `request_id`         | 联系支持时请提供。用这个 id 调用 `GET /v1/tasks/{id}`，会在 `output` 下返回同一份结果，响应丢了也不等于结果丢了。            |
| `country`、`language` | 实际使用的市场，只在接受市场的工具上出现。                                                                 |
| `domain`             | 实际使用的域名，只在接受域名的工具上出现。完整 URL 会被截取为域名，开头的 `www.` 会被去掉。                                  |
| `results[]`          | 数据行，只在返回列表的工具上出现。其他工具的字段放在顶层。                                                         |
| `billed_rows`        | 本次调用计费的行数。                                                                            |
| `has_data`           | 出现在 `domain-overview`、`backlink-summary` 以及 Domain Rating 和站点流量工具上。`false` 表示该域名没有记录。 |
| `usage`              | 位于每个响应末尾：本次调用的费用。                                                                     |

`usage.price_usd` 是结算后的扣费，单位为美元。`billing_unit` 始终为 `request`，`quantity` 始终为 `1`；`billed_rows` 说明这笔费用覆盖了多少行。

数据里没有的数字不会出现在行里，使用前请先判断字段是否存在。未知请求字段会被 `400 bad_request` 拒绝：字段拼错却被悄悄忽略，返回的就是另一个问题的答案。

## 关键词工具

### 关键词概览

`POST https://api.beatapi.io/v1/seo/keyword-overview`

查询已有关键词的搜索量、CPC、竞争度、难度、意图和逐月历史。没人搜索的关键词不会返回，也不会写成零。

| 字段         | 类型        | 必填 | 说明                                        |
| ---------- | --------- | -: | ----------------------------------------- |
| `keywords` | string\[] |  是 | 1–100 个关键词，每个不超过 80 个字符。关键词会转成小写，重复的只算一次。 |
| `country`  | string    |  否 | 见[国家和语言](#country-and-language)。          |
| `language` | string    |  否 | 见[国家和语言](#country-and-language)。          |

响应示例见[快速开始](#quick-start)。每行的字段：

| 字段                   | 说明                                                               |
| -------------------- | ---------------------------------------------------------------- |
| `keyword`            | 关键词。                                                             |
| `search_volume`      | 该市场的月搜索量。                                                        |
| `cpc_usd`            | 付费广告的单次点击费用，单位为美元。                                               |
| `competition`        | 广告主竞争度，取值 0 到 1。                                                 |
| `keyword_difficulty` | 关键词排名的难度，取值 0 到 100。                                             |
| `intent`             | 主要搜索意图，如 `informational` 或 `navigational`。                       |
| `updated_at`         | 该关键词数据的最近更新时间。                                                   |
| `monthly_searches[]` | 每个月的 `year`、`month` 和 `search_volume`。只在 `keyword-overview` 中返回。 |

### 关键词拓展

`POST https://api.beatapi.io/v1/seo/keyword-ideas`

根据种子关键词返回相关关键词，最相关的排在前面。每行的字段与 `keyword-overview` 相同，但没有 `monthly_searches`。

| 字段                   | 类型        | 必填 | 说明                                     |
| -------------------- | --------- | -: | -------------------------------------- |
| `keywords`           | string\[] |  是 | 1–20 个种子关键词，每个不超过 80 个字符。              |
| `limit`、`offset`     | integer   |  否 | 见 [limit 和 offset](#limit-and-offset)。 |
| `country`、`language` | string    |  否 | 见[国家和语言](#country-and-language)。       |

```bash
curl https://api.beatapi.io/v1/seo/keyword-ideas \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["redis sentinel"],"limit":20}'
```

### 关键词难度

`POST https://api.beatapi.io/v1/seo/keyword-difficulty`

一次查询多个关键词，只返回 `keyword_difficulty`。接受的字段与 `keyword-overview` 相同。

```json
{
  "object": "seo.keyword_difficulty",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "results": [
    { "keyword": "redis cluster", "keyword_difficulty": 15 },
    { "keyword": "redis sentinel", "keyword_difficulty": 2 }
  ],
  "billed_rows": 2,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0186",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

## 域名工具

这四个工具都接受 `domain`（如 `example.com`），以及 `country` 和 `language`。

### 域名概览

`POST https://api.beatapi.io/v1/seo/domain-overview`

域名在一个市场里的自然和付费搜索足迹。这里只有搜索流量，不是站点总访问量。

```bash
curl https://api.beatapi.io/v1/seo/domain-overview \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","country":"us"}'
```

```json
{
  "object": "seo.domain_overview",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "has_data": true,
  "organic": {
    "ranking_keywords": 22125,
    "search_traffic_estimate": 108626.58,
    "traffic_value_usd_estimate": 483101.98,
    "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
    "new": 18919,
    "up": 1048,
    "down": 1105,
    "lost": 4041
  },
  "paid": { "ranking_keywords": 0, "search_traffic_estimate": 0 },
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 字段                           | 说明                                                        |
| ---------------------------- | --------------------------------------------------------- |
| `ranking_keywords`           | 在该市场有排名的关键词数。                                             |
| `search_traffic_estimate`    | 估算的月搜索流量。                                                 |
| `traffic_value_usd_estimate` | 用广告买到这些流量的估算费用，单位为美元。                                     |
| `rank_distribution`          | 按排名位置统计的关键词数：`1`、`2-3`、`4-10`、`11-20`、`21-30` 和 `31-100`。 |
| `new`、`up`、`down`、`lost`     | 最近开始有排名、排名上升、排名下降和不再有排名的关键词数。                             |

没有记录的域名返回 `has_data: false`，既没有 `organic` 也没有 `paid`。这表示没有数据，不是流量为零，调用照常计费。

### 排名关键词

`POST https://api.beatapi.io/v1/seo/ranked-keywords`

域名在一个市场里有排名的关键词，搜索量最高的排在前面。

| 字段                   | 类型      | 必填 | 说明                                             |
| -------------------- | ------- | -: | ---------------------------------------------- |
| `domain`             | string  |  是 | 域名。                                            |
| `contains`           | string  |  否 | 只返回包含这段文字的关键词，最多 80 个字符，不区分大小写。`%` 和 `_` 会被拒绝。 |
| `limit`、`offset`     | integer |  否 | 见 [limit 和 offset](#limit-and-offset)。         |
| `country`、`language` | string  |  否 | 见[国家和语言](#country-and-language)。               |

```bash
curl https://api.beatapi.io/v1/seo/ranked-keywords \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","contains":"cluster","limit":1}'
```

```json
{
  "object": "seo.ranked_keywords",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 108,
  "results": [
    {
      "keyword": "redis cluster",
      "search_volume": 590,
      "cpc_usd": 15.62,
      "competition": 0.17,
      "keyword_difficulty": 15,
      "intent": "informational",
      "updated_at": "2026-10-16 01:53:48 +00:00",
      "position": 1,
      "absolute_position": 2,
      "url": "https://redis.io/docs/cluster/",
      "title": "Redis cluster",
      "position_seen_at": "2026-09-14 04:53:47 +00:00",
      "search_traffic_estimate": 12.35
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

每行在 `keyword-ideas` 的字段之外增加：

| 字段                        | 说明                             |
| ------------------------- | ------------------------------ |
| `position`                | 在自然搜索结果中的位置。                   |
| `absolute_position`       | 把结果页上所有元素都算在内的位置。              |
| `url`、`title`             | 获得排名的页面。                       |
| `position_seen_at`        | 记录该排名的时间。排名是快照，可能是几周甚至几个月前的数据。 |
| `search_traffic_estimate` | 该关键词为页面带来的估算月搜索流量。             |

### 热门页面

`POST https://api.beatapi.io/v1/seo/top-pages`

域名下的页面，估算搜索流量最高的排在前面。字段：`domain`、`limit`、`offset`、`country`、`language`。每行有 `url` 和该页面的[足迹字段](#domain-overview)。

```json
{
  "object": "seo.top_pages",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 1104,
  "results": [
    {
      "url": "https://redis.io/",
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58,
      "traffic_value_usd_estimate": 483101.98,
      "rank_distribution": { "1": 987, "2-3": 491, "4-10": 2245, "11-20": 5678, "21-30": 3224, "31-100": 9500 },
      "new": 18919,
      "up": 1048,
      "down": 1105,
      "lost": 4041
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

### 竞争对手

`POST https://api.beatapi.io/v1/seo/competitors`

和某域名竞争相同搜索关键词的域名。字段：`domain`、`limit`、`offset`、`country`、`language`。结果里不含该域名自身和最大的综合站点（如 youtube.com、wikipedia.org），`total` 只统计剩下的部分。

```json
{
  "object": "seo.competitors",
  "request_id": "task_xxx",
  "country": "us",
  "language": "en",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 9,
  "results": [
    {
      "domain": "example.com",
      "shared_keywords": 4706,
      "avg_position": 29.6,
      "ranking_keywords": 22125,
      "search_traffic_estimate": 108626.58
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0183",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 字段                        | 说明             |
| ------------------------- | -------------- |
| `domain`                  | 竞争域名。          |
| `shared_keywords`         | 两个域名都有排名的关键词数。 |
| `avg_position`            | 它在这些关键词上的平均排名。 |
| `ranking_keywords`        | 它有排名的关键词总数。    |
| `search_traffic_estimate` | 它的估算月搜索流量。     |

## 外链工具

### 外链概况

`POST https://api.beatapi.io/v1/seo/backlink-summary`

域名的外链情况。唯一的字段是 `domain`。

```json
{
  "object": "seo.backlink_summary",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "link_authority": 500,
  "backlinks": 920428,
  "referring_domains": 32647,
  "referring_main_domains": 28596,
  "referring_pages": 748383,
  "referring_ips": 19191,
  "broken_backlinks": 8482,
  "broken_pages": 2773,
  "spam_score": 28,
  "first_seen": "2019-01-15 22:56:44 +00:00",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 字段                                           | 说明                               |
| -------------------------------------------- | -------------------------------- |
| `link_authority`                             | 外链情况的权威度，取值 0 到 1000，是本数据集自己的刻度。 |
| `backlinks`                                  | 找到的外链数。                          |
| `referring_domains`、`referring_main_domains` | 链接到它的域名数，以及子域名合并计为一个后的域名数。       |
| `referring_pages`、`referring_ips`            | 链接到它的页面数和 IP 地址数。                |
| `broken_backlinks`、`broken_pages`            | 失效的外链数，以及该域名下已失效的页面数。            |
| `spam_score`                                 | 外链情况的垃圾分。越高越可能是垃圾链接。             |
| `first_seen`                                 | 首次发现指向该域名的链接的时间。                 |

域名没有记录时 `has_data` 为 `false`，没有其他字段，调用照常计费。

### 外链列表

`POST https://api.beatapi.io/v1/seo/backlinks`

指向一个域名的链接，最强的排在前面。

| 字段               | 类型      | 必填 | 说明                                      |
| ---------------- | ------- | -: | --------------------------------------- |
| `domain`         | string  |  是 | 域名。                                     |
| `one_per_domain` | boolean |  否 | 默认 `true`：每个来源域名一条链接。设为 `false` 可取全部链接。 |
| `limit`、`offset` | integer |  否 | 见 [limit 和 offset](#limit-and-offset)。  |

```json
{
  "object": "seo.backlinks",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "limit": 1,
  "offset": 0,
  "total": 28843,
  "results": [
    {
      "source_url": "https://blog.example.com/caching",
      "source_domain": "blog.example.com",
      "source_title": "Caching notes",
      "source_authority": 493,
      "source_country": "CZ",
      "target_url": "https://redis.io/",
      "anchor": "Redis",
      "link_type": "anchor",
      "dofollow": true,
      "spam_score": 3,
      "first_seen": "2025-04-26 07:12:33 +00:00",
      "last_seen": "2026-06-18 19:14:30 +00:00",
      "is_new": false,
      "is_lost": false,
      "is_broken": false
    }
  ],
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.0352",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 字段                                          | 说明                                |
| ------------------------------------------- | --------------------------------- |
| `source_url`、`source_domain`、`source_title` | 发出链接的页面。                          |
| `source_authority`                          | 来源域名的 link authority，取值 0 到 1000。 |
| `source_country`                            | 来源域名所在的国家。                        |
| `target_url`、`anchor`                       | 被链接的页面和链接文字。                      |
| `link_type`                                 | 链接类型，如 `anchor`。                  |
| `dofollow`                                  | 该链接是否传递权重。                        |
| `spam_score`                                | 该链接的垃圾分。越高越可能是垃圾链接。               |
| `first_seen`、`last_seen`                    | 首次和最后一次发现该链接的时间。                  |
| `is_new`、`is_lost`、`is_broken`              | 该链接是新出现的、已消失，还是已失效。               |

## 如何解读数字

* **搜索流量。** `search_traffic_estimate` 是估算的搜索流量，不是站点总访问量。
* **都是估算。** 流量和价值数字都是估算，不是对站点的实测。
* **Link authority。** `link_authority` 取值 0 到 1000，是本数据集自己的刻度。
* **关键词难度**是本数据集自己的刻度，不要和其他工具的分数比较。
* **缺失不等于零。** 缺失的数字表示未知，绝不等于零。
* **没有实时结果页。** 没有实时结果页工具。要查域名在某个关键词上的排名，请用 [`ranked-keywords`](#ranked-keywords) 加 `contains`。返回的是最后记录的排名，不是实时排名。
* **Domain Rating 和站点流量**的说明单独放在[如何解读这些数字](#reading-these-numbers)。

## 计费

| 工具                                                                                                                          |      按次 |    每返回一行 |
| --------------------------------------------------------------------------------------------------------------------------- | ------: | -------: |
| `keyword-overview`, `keyword-ideas`, `keyword-difficulty`, `domain-overview`, `ranked-keywords`, `top-pages`, `competitors` | \$0.018 | \$0.0003 |
| `backlink-summary`, `backlinks`                                                                                             | \$0.035 | \$0.0002 |

Domain Rating 和站点流量有[单独的价格](#prices-of-these-tools)。

* `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` 配合下面的引用来调用：

| 引用                            | 工具                   |
| ----------------------------- | -------------------- |
| `data:seo.keyword_overview`   | `keyword-overview`   |
| `data:seo.keyword_ideas`      | `keyword-ideas`      |
| `data:seo.keyword_difficulty` | `keyword-difficulty` |
| `data:seo.domain_overview`    | `domain-overview`    |
| `data:seo.ranked_keywords`    | `ranked-keywords`    |
| `data:seo.top_pages`          | `top-pages`          |
| `data:seo.competitors`        | `competitors`        |
| `data:seo.backlink_summary`   | `backlink-summary`   |
| `data:seo.backlinks`          | `backlinks`          |

Domain Rating 和站点流量的引用[和这些工具列在一起](#references-for-agents)。

Inspect 会显示输入结构和当前价格。`input` 就是该工具的请求体，Run 直接返回结果：

```json
{ "reference": "data:seo.ranked_keywords", "operation": "start", "input": { "domain": "redis.io", "contains": "cluster", "limit": 20 } }
```

同样的三个调用也可以走 REST：`POST /v1/capabilities/search`、`/v1/capabilities/inspect` 和 `/v1/capabilities/run`。详见[能力接口](/capabilities)。

## 错误

错误使用 BeatAPI 标准错误结构，每个错误都带 `retryable`。重试策略见[错误说明](/errors)。

```json
{
  "error": {
    "code": "bad_request",
    "message": "country 'cn' is not covered; use a two-letter code such as us, gb, de or jp (China is not covered)",
    "retryable": false,
    "request_id": "req_abc123"
  }
}
```

| HTTP 状态码 | 错误码                                                                 | 含义                                      |
| -------: | ------------------------------------------------------------------- | --------------------------------------- |
|      400 | `bad_request`                                                       | 字段无效或未知，关键词或域名不合法，或市场不在覆盖范围内。错误信息会指出字段。 |
|      401 | `missing_api_key` / `invalid_api_key`                               | 没有发送密钥，或密钥错误、已过期、已禁用、额度已用完。             |
|      402 | `insufficient_credits`                                              | 余额不足：余额为零或低于本次调用的价格。                    |
|      403 | `forbidden`                                                         | 该密钥或账户无权进行此调用。                          |
|      409 | `idempotency_conflict`                                              | `Idempotency-Key` 被用于不同的请求体。            |
|      429 | `rate_limit_exceeded`                                               | 请求过多。请等待 `retry_after_seconds`。         |
|      500 | `internal_error`                                                    | 意外的内部错误，可重试。                            |
|      503 | `processing_unavailable`、`processing_timeout` 或 `processing_failed` | SEO 数据暂时不可用，或调用耗时过长。请退避后重试。             |

`503` 绝不收费。BeatAPI 不返回 `502`。

## Domain Rating 与站点流量

另外三个工具的用法相同：同样的密钥，同样在响应里返回结果，同样的 `usage` 和错误。它们接受 `domain`，没有市场概念，因此 `country` 和 `language` 会被拒绝。也没有 `limit` 或 `offset`。

| 你想要                    | 工具                      |
| ---------------------- | ----------------------- |
| SEO 团队用来比较域名的 0–100 分数 | `domain-rating`         |
| 这个分数的逐月变化              | `domain-rating-history` |
| 站点的总访问量、访问来源和访客行为      | `site-traffic`          |

### Domain Rating

`POST https://api.beatapi.io/v1/seo/domain-rating`

```bash
curl https://api.beatapi.io/v1/seo/domain-rating \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io"}'
```

```json
{
  "object": "seo.domain_rating",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "domain_rating": 90,
  "link_rank": 1927,
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

`domain_rating` 取值 0 到 100。`link_rank` 是域名按链接计算的全球排名，数值越低越强。

### Domain Rating 历史

`POST https://api.beatapi.io/v1/seo/domain-rating-history`

```json
{
  "object": "seo.domain_rating_history",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "has_data": true,
  "results": [
    { "month": "2025-12", "domain_rating": 89 },
    { "month": "2026-01", "domain_rating": 89 },
    { "month": "2026-02", "domain_rating": 89 },
    { "month": "2026-03", "domain_rating": 89 },
    { "month": "2026-04", "domain_rating": 89 },
    { "month": "2026-05", "domain_rating": 89 },
    { "month": "2026-06", "domain_rating": 90 },
    { "month": "2026-07", "domain_rating": 90 },
    { "month": "2026-08", "domain_rating": 90 },
    { "month": "2026-09", "domain_rating": 90 },
    { "month": "2026-10", "domain_rating": 90 }
  ],
  "billed_rows": 11,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.044",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

未知域名返回 `has_data: false`、空的 `results` 和 `billed_rows: 1`。

### 站点流量

`POST https://api.beatapi.io/v1/seo/site-traffic`

网站来自所有渠道的估算总访问量，以及来源、国家、排名和参与度。

| 字段       | 类型      | 必填 | 说明                       |
| -------- | ------- | -: | ------------------------ |
| `domain` | string  |  是 | 域名。                      |
| `months` | integer |  否 | 历史月数：`3`（默认）、`6` 或 `12`。 |

```bash
curl https://api.beatapi.io/v1/seo/site-traffic \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"redis.io","months":3}'
```

```json
{
  "object": "seo.site_traffic",
  "request_id": "task_xxx",
  "domain": "redis.io",
  "months": 3,
  "has_data": true,
  "site_visits_estimate": 734682,
  "monthly_visits": [
    { "month": "2026-07", "visits": 827501 },
    { "month": "2026-08", "visits": 789909 },
    { "month": "2026-09", "visits": 734682 }
  ],
  "global_rank": 66213,
  "country_rank": { "country": "IN", "rank": 19016 },
  "category": "computers_electronics_and_technology/programming_and_developer_software",
  "category_rank": 634,
  "bounce_rate": 0.4254,
  "pages_per_visit": 3.3174,
  "avg_visit_seconds": 116.2764,
  "traffic_sources": {
    "direct": 0.3293,
    "search": 0.4836,
    "paid_search": 0.0072,
    "social": 0.0435,
    "paid_social": 0.0026,
    "referrals": 0.0992,
    "mail": 0.0114,
    "display_ads": 0.0035,
    "affiliate": 0,
    "gen_ai": 0.0197
  },
  "top_countries": [{ "country": "IN", "share": 0.1995 }],
  "top_keywords": [{ "keyword": "redis", "search_volume": 193980, "cpc_usd": 2.78 }],
  "title": "Redis - Real-time data for agents & apps",
  "description": "Developers love Redis. Unlock the full potential of the Redis database with Redis Enterprise and start building blazing fast apps.",
  "billed_rows": 1,
  "usage": {
    "billing_unit": "request",
    "quantity": 1,
    "price_usd": "0.005",
    "price_version": "web_3f9a1c2b7d10"
  }
}
```

| 字段                                    | 说明                                        |
| ------------------------------------- | ----------------------------------------- |
| `site_visits_estimate`                | 最近一个月的估算访问量。                              |
| `monthly_visits[]`                    | 每个月的 `month` 和 `visits`。                  |
| `global_rank`                         | 在所有站点中的排名。数值越低，站点越大。                      |
| `country_rank`                        | 在一个国家内的排名：`country` 和 `rank`。             |
| `category`、`category_rank`            | 站点的类别及其在该类别内的排名。                          |
| `bounce_rate`                         | 只看一页就离开的访问占比，取值 0 到 1。                    |
| `pages_per_visit`、`avg_visit_seconds` | 每次访问浏览的页数，以及平均访问时长（秒）。                    |
| `traffic_sources`                     | 各渠道的访问占比，取值 0 到 1。                        |
| `top_countries[]`                     | 访问量最多的国家，`share` 是各自 0 到 1 的占比。           |
| `top_keywords[]`                      | 带来搜索访问的关键词，附 `search_volume` 和 `cpc_usd`。 |
| `title`、`description`                 | 站点自己的标题和描述。                               |

### 如何解读这些数字

* **两种流量。** `search_traffic_estimate` 是估算的搜索流量；`site_visits_estimate` 是来自所有渠道的总访问量。两者是不同的度量，绝不要相加或比较。访问量不是独立访客数。
* **两种权威分。** `link_authority` 取值 0 到 1000，是本数据集自己的刻度；`domain_rating` 取值 0 到 100。两者不能互相换算。
* **没有记录。** `has_data: false` 表示该域名没有记录，这和评分或流量为零不同：新站点的评分可以是 `0`，同时仍有 `link_rank`。

### 这些工具的价格

| 工具                      |             价格 |
| ----------------------- | -------------: |
| `domain-rating`         |   每次调用 \$0.005 |
| `domain-rating-history` | 每返回一个月 \$0.004 |
| `site-traffic`，3 个月     |        \$0.005 |
| `site-traffic`，6 个月     |         \$0.01 |
| `site-traffic`，12 个月    |        \$0.015 |

* `has_data` 为 `false` 时，`domain-rating` 和 `site-traffic` 照常计费。`domain-rating-history` 查询未知域名时不返回月份，按一个月收费，即 \$0.004。
* 被拒绝的请求（`400`）和失败的调用（`503`）不收费。
* `domain-rating-history` 运行前，余额必须够付 24 个月的历史。之后只按实际返回的内容收费。

### Agent 引用

| 引用                               | 工具                      |
| -------------------------------- | ----------------------- |
| `data:seo.domain_rating`         | `domain-rating`         |
| `data:seo.domain_rating_history` | `domain-rating-history` |
| `data:seo.site_traffic`          | `site-traffic`          |