> 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 > 1 つの BeatAPI キーで、キーワードデータ、ドメインの順位、被リンク、Domain Rating、サイトトラフィックを取得できます。12 のツールはすべてレスポンスで結果を返し、アプリケーションからもエージェントからも利用できます。 12 のツールで、アプリケーションやエージェントに SEO データを提供します。キーワードの検索数と上位表示の難しさ、ドメインに検索トラフィックをもたらすキーワードとページ、競合、リンク元、Domain Rating、サイトの訪問数を取得できます。各ツールは `/v1/seo/` 以下の 1 つの `POST` で、BeatAPI API キーを使い、1 回のレスポンスで結果を返します。エージェントは同じツールを[ケイパビリティ](#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" } } ``` ## 認証 すべての呼び出しで、BeatAPI API キーを `Authorization: Bearer ` として送信します。キーは `sk-` プレフィックスの有無を問いません。キーは[ダッシュボード → API Keys](https://beatapi.io/dashboard/apikeys) で作成できます。すべてのツールは `https://api.beatapi.io` で提供され、アカウントの残高から課金されます。 ## ツールを選ぶ | 目的 | ツール | | ---------------------------------------- | -------------------- | | 手元のキーワードの検索ボリューム、CPC、難易度、検索意図、月別の履歴を知りたい | `keyword-overview` | | トピックに関連する新しいキーワードを見つけたい | `keyword-ideas` | | キーワードのリストの難易度だけを知りたい | `keyword-difficulty` | | 1 つの市場におけるドメインの検索フットプリントを知りたい | `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` | 2 文字の小文字コードです（`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 文字以内です。小文字に変換され、重複は 1 つとして扱います。 | | `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" } } ``` ## ドメインツール 4 つのツールはいずれも `example.com` のような `domain` と、`country`、`language` を受け取ります。 ### ドメインの概要 `POST https://api.beatapi.io/v1/seo/domain-overview` 1 つの市場におけるドメインのオーガニック検索と有料検索のフットプリントです。検索トラフィックのみで、サイトの総訪問数ではありません。 ```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` 1 つの市場でドメインが順位を持つキーワードを、検索ボリュームの多い順に返します。 | フィールド | 型 | 必須 | 説明 | | -------------------- | ------- | --: | --------------------------------------------------------------- | | `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` | リンク元のドメイン数と、サブドメインを 1 つとして数えた場合の数です。 | | `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` で、リンク元ドメインごとに 1 件を返します。すべてのリンクを取得するには `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` | リンク元ドメインのリンクの権威性です（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` はこのデータセット独自の尺度で 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` は 1 件のレコードを返し、これを 1 行として数えます。`has_data` が `false` の場合は 0 行です。100 行を返す `ranked-keywords` の呼び出しは \$0.048 です。 * 何も見つからなかった呼び出しにも呼び出しごとの料金がかかります。拒否されたリクエスト（`400`）と失敗した呼び出し（`503`）は課金されません。 * 呼び出しの実行前に、残高が最大料金（`limit` のすべての行、または送信したすべてのキーワード）を満たしている必要があります。その後、実際に返した分だけ課金されます。 * クライアントが同じリクエストを再試行する可能性がある場合は、`Idempotency-Key` ヘッダーを送信してください。同じキーを異なるボディで再利用すると `409 idempotency_conflict` で拒否されます。 ## エージェント SEO データ専用の MCP ツールはありません。BeatAPI MCP エンドポイント `https://beatapi.io/mcp` で、エージェントは `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 } } ``` 同じ 3 つの呼び出しは REST でも利用できます：`POST /v1/capabilities/search`、`/v1/capabilities/inspect`、`/v1/capabilities/run`。[Capabilities API](/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 とサイトトラフィック さらに 3 つのツールが同じ方法で利用できます。キーは同じで、結果はレスポンスで返り、`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` | 直近 1 か月の推定訪問数です。 | | `monthly_visits[]` | 月ごとの `month` と `visits` です。 | | `global_rank` | 全サイト内の順位です。値が小さいほど規模の大きなサイトです。 | | `country_rank` | 1 つの国の中での順位です：`country` と `rank`。 | | `category`、`category_rank` | サイトのカテゴリと、その中での順位です。 | | `bounce_rate` | 1 ページだけ見て離脱した訪問の割合です（0～1）。 | | `pages_per_visit`、`avg_visit_seconds` | 1 回の訪問あたりの閲覧ページ数と、平均訪問時間（秒）です。 | | `traffic_sources` | 各チャネルからの訪問の割合です（0～1）。 | | `top_countries[]` | 訪問数の多い国と、それぞれの `share`（0～1）です。 | | `top_keywords[]` | 検索からの訪問をもたらすキーワードと、その `search_volume`、`cpc_usd` です。 | | `title`、`description` | サイト自身のタイトルと説明です。 | ### これらの数値の読み方 * **2 種類のトラフィック：** `search_traffic_estimate` は推定検索トラフィックで、`site_visits_estimate` は全チャネルからの総訪問数です。これらは異なる指標なので、合算したり比較したりしないでください。訪問数はユニークビジター数ではありません。 * **2 種類の権威スコア：** `link_authority` はこのデータセット独自の尺度で 0～1000 の値を取り、`domain_rating` は 0～100 の値を取ります。相互に換算することはできません。 * **記録なし：** `has_data: false` はドメインの記録がないことを示し、レーティングやトラフィックがゼロであることとは異なります。新しいサイトのレーティングが `0` でも、`link_rank` がある場合があります。 ### これらのツールの料金 | ツール | 料金 | | ----------------------- | ------------------: | | `domain-rating` | 1 回の呼び出しにつき \$0.005 | | `domain-rating-history` | 返した 1 か月につき \$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` は月を返しませんが、1 か月分の \$0.004 がかかります。 * 拒否されたリクエスト（`400`）と失敗した呼び出し（`503`）は課金されません。 * `domain-rating-history` の実行前に、残高が 24 か月分の履歴の料金を満たしている必要があります。その後、実際に返した分だけ課金されます。 ### エージェント向けの参照 | 参照 | ツール | | -------------------------------- | ----------------------- | | `data:seo.domain_rating` | `domain-rating` | | `data:seo.domain_rating_history` | `domain-rating-history` | | `data:seo.site_traffic` | `site-traffic` |