seo-api

https://api.seranking.com/mcp の SE Ranking MCP をライブで利用します。ツールスキーマはライブでイントロスペクションされます。このスキルは、API サーフェスの固定スナップショットには依存しません。

SE Ranking API 統合アーキテクト

開発者が SE Ranking SEO Data API と Project API を使った実用的な統合を構築できるよう支援します。成果物は、コードレシピ（すぐに貼り付けて使える cURL／Python／TypeScript／MCP ツール呼び出しの手順）、Project API の状態のライブ接続（プロジェクトの作成、キーワードの追加、監査の設定、AIRT プロンプトの設定）、またはその両方です。このスキルは、195 個のツールから成るサーフェス全体、すべての呼び出しにかかるクレジットとレート制限のコスト、主要な MCP クライアントごとの標準的なセットアップ方法を把握しています。

前提条件

• SE Ranking MCP が接続済みであること：https://api.seranking.com/mcp。統合ゲートウェイを通じて、単一の API キーで DATA_* と PROJECT_* の両方のツールを認証します。/mcp に se-ranking が表示されない場合、このスキルはインストールコマンドを出力して停止します。references/auth-and-keys.md を参照してください。
• （任意）WebFetch：リクエストに JSON Schema を超える説明が必要な場合に、seranking.com/api/data/* および seranking.com/api/project/* にある詳細ガイドを取得します。
• ユーザーが、平易な言葉で統合の目的を提示します（例：「クライアント X 向けのランクトラッカーを構築する」「50 個のドメインのすべてのバックリンクを毎週 BigQuery に取り込む」「新しいプロジェクトの監査と AIRT プロンプトを設定する」）。目的が曖昧な場合に限り、このスキルは質問をして確認します。

プロセス

1. 事前確認。

   • SE Ranking MCP に到達できることを確認します。到達できない場合は、次を出力します。

     claude mcp add --transport http se-ranking https://api.seranking.com/mcp
     

     そして停止します。OAuth と X-Api-Key ヘッダーのトレードオフ、ヘッドレス環境／CI のパターンについては、references/auth-and-keys.md を参照してください。
   • DATA_getSubscription を呼び出します（0 クレジット）。units_left、プランのステータス、有効期限を記録します。使用可能クレジット数の予測には units_left の数値を使い、ステップ 5 のコスト予測にも表示します。必要に応じて、{ limit, used } の形式で確認できる DATA_getCreditBalance も呼び出せます。ただし、2 つは同じものではありません。異なる残りクレジット数が返され、整合しないためです（約 860 万の差は通常の範囲です）。そのため、getSubscription.units_left を正としてください。

2. 目的を明確にする。 目的が曖昧な場合に限り、1～3 個の質問をします。ユーザーがすでに明確に説明している場合は省略します。確認に役立つ質問：

   • 「これは一度だけの実行、定期ジョブ（日次／週次）、それとも製品内の長期的な統合ですか？」
   • 「対象の国／言語／デバイス、または全世界ですか？」
   • 「SE Ranking で既に所有しているプロジェクトを操作しますか、それともドメインの調査だけを行いますか？」

3. 対象となる API サーフェスを特定します。 目的を次の一方または両方に対応付けます。

   • Data API — 事前のアカウント設定なしで、任意のドメインを対象に調査データを取得できます。クレジット制です。references/api-surface-map.md の「Data API surfaces」を参照してください。
   • Project API — ユーザー自身の SE Ranking プロジェクトに対する操作（順位追跡、監査、AIRT、バックリンクグループ、マーケティングプラン、サブアカウント）です。サブスクリプション上限に基づく課金で、クレジット制ではありません。Business または Enterprise プランが必要です。references/api-surface-map.md の「Project API surfaces」を参照してください。
   • 実際の統合では、両方にまたがるケースが多くあります。たとえば、ランクトラッカーのセットアップでは PROJECT_createProject + PROJECT_addKeywords + PROJECT_runPositionCheck を使い、その後のレポートでは同じドメインに対して DATA_getDomainKeywords を使います。

4. ツール／エンドポイントに対応付けます。 統合の各ステップについて、以下を明記します。

   • MCP ツール：`DATA_getDomainKeywords`または `PROJECT_addKeywords`。
   • 基盤となる REST エンドポイントと HTTP メソッド（例：GET /v1/domain/keywords）。
   • クレジットコスト（Data API）または消費する上限（Project API）。コストは references/rate-limits-and-credits.md と seranking.com/api/data/* の各エンドポイントページを参照します。MCP ツールの description フィールドには入力スキーマと使用上の注意が記載されていますが、クレジットコストは記載されていません。
   • ツールにユーザーが指定していない ID（プロジェクト ID、検索エンジン ID、地域名、言語コード）が必要な場合は、その前に必須の *list* または *available* 呼び出しを挿入します。references/api-surface-map.md §「ID resolution」を参照してください。

5. コストを予測します。 すべての Data API 呼び出しのクレジットコストを合計します。Project API 呼び出しについては、プラン上限への影響を示します（例：「この処理では、プランから Site × 1、Keywords × 50、Audit Pages 約 500 を消費します」）。以下と照合します。

   • ステップ 1 の units_left。不足している場合は、その旨とアップグレードリンクを提示して停止します。
   • Project API ツールを使う場合は、プラン上限。PROJECT_getUserProfile で現在の使用状況を取得し、統合によって上限を超える場合はその旨を伝えます。

6. 実行モードを選択します。 以下について、必ずユーザーに明示的に確認します。

   • コードモード — そのまま貼り付けて使える cURL、Python（requests）、TypeScript（fetch）、MCP ツール呼び出しの各パターンを出力します。開発者が実行します。読み取り専用の調査、ユーザー自身が管理したい定期ジョブ、Claude のセッション外にデプロイしたい処理では、これを既定とします。
   • ライブモード — MCP を介して統合を一つずつ実行します。変更を伴う呼び出しはすべて確認します。ユーザーがこの会話の終了時点で状態が存在することを望む、一度限りの Project API 設定（新規プロジェクトの作成、キーワードの追加、監査の設定、AIRT プロンプトグループの設定など）では、これを既定とします。
   • ハイブリッド — 一度限りの設定をライブで行い、定期的な処理のコードを出力します（例：「プロジェクトを作成し、キーワードを 50 個追加しました。こちらは、順位を取得して BigQuery に書き込む日次実行用の Python スクリプトです」）。

7. 実行するか、出力します。

   • コードモード — code/curl.sh、code/python.py、code/typescript.ts、code/mcp-calls.md を作成します。各ファイルは断片ではなく、単独で実行できる完全なサンプルにします。429（レート制限）および 403（クレジット不足）のエラー処理を含めます。標準的なパターンのスニペットについては、references/integration-patterns.md を参照してください。
   • ライブモード — 変更を伴う呼び出し（PROJECT_create*、PROJECT_add*、PROJECT_delete*、PROJECT_update*、DATA_createStandardAudit、DATA_createAdvancedAudit など）ごとに、確認メッセージを 1 行で表示します。

     PROJECT_createProject(domain="acme.com", name="ACME Inc — Rank Tracker", country="us") を実行しようとしています。
     消費量：サブスクリプションから「Site」を 1 件消費します。続行しますか？ [y/N]
     

     明示的な y / yes を待ちます。それ以外の場合は実行せず、代わりに同等のコードを出力するコードモードに切り替えます。読み取り専用の呼び出し（DATA_get*、DATA_list*、PROJECT_get*、PROJECT_list*）は確認なしで実行します。すべての呼び出しを、タイムスタンプ、引数、レスポンスのステータスとともに evidence/03-execution-log.md に記録します。

8. RECIPE.md を作成します。 モードにかかわらず、必ず作成します。開発者が構築したもの、または構築方法を理解するための成果物です。以下の出力形式を参照してください。

出力形式

フォルダー seo-api-{slug}-{YYYYMMDD}/。{slug} は目標の概要を表すケバブケースの名前です（例：acme-rank-tracker、bulk-backlinks-bigquery）。

seo-api-{slug}-{YYYYMMDD}/
├── RECIPE.md                       (primary deliverable — what was built or how to build it)
├── code/
│   ├── curl.sh                     (cURL one-liners + multi-step bash)
│   ├── python.py                   (idiomatic requests-based script)
│   ├── typescript.ts               (fetch + zod-validated responses)
│   └── mcp-calls.md                (MCP-tool-call sequence — same workflow, agent-native)
└── evidence/
    ├── 01-preflight.md             (credit balance, subscription status, MCP connectivity check)
    ├── 02-cost-forecast.md         (per-call cost breakdown, plan-limit deltas, total)
    ├── 03-ids-resolved.md          (Project API / search-engine IDs, geo codes resolved upfront — omit if none needed)
    └── 04-execution-log.md         (every MCP call executed, with args + status — omit in pure code mode where nothing ran)

最上位には RECIPE.md と code/ を配置します。evidence/ フォルダーには推論の過程を保存します。監査担当者は 02-cost-forecast.md と実行ログを重視します。03 と 04 は条件付きです。ID の照合も呼び出しの実行もない場合（純粋なコードモードのアドバイス）は、01 と 02 のみを含めます。

RECIPE.md は次の形式に従います。

# {Integration Title}: {target}

> Run dated {YYYY-MM-DD} · Mode: {code | live | hybrid} · Total cost: {n} credits + {plan-limits consumed}

## Goal

{1–2 sentences. What was asked, what's being shipped.}

## API surface map

| Step | MCP tool | REST endpoint | Verb | Cost |
|------|----------|---------------|------|------|
| 1    | `DATA_getCreditBalance` | `/v1/account/subscription` | GET | 0 credits |
| 2    | `PROJECT_listProjects` | `/v1/account/projects` | GET | 0 (plan limit: read) |
| 3    | `PROJECT_createProject` | `/v1/projects` | POST | 1 Site from plan |
| ...  | ... | ... | ... | ... |

## Auth & setup

{cURL header / Python session / TypeScript fetch wrapper showing exactly how to authenticate. Reference `references/auth-and-keys.md` for OAuth vs. header tradeoffs.}

## Cost forecast

- Credit cost (Data API): {n} credits ({explanation per call})
- Plan-limit consumption (Project API): {Sites: n, Keywords: n, Audit Pages: n, AIRT Prompts: n}
- Your balance at run time: {units_left} credits, {plan limits available}
- {OK / WARNING: this integration would push X over plan limit}

## Recipe

### Option A — cURL

(complete bash script in `code/curl.sh`)

### Option B — Python

(complete script in `code/python.py`)

### Option C — TypeScript

(complete script in `code/typescript.ts`)

### Option D — MCP tool calls

(agent-native sequence in `code/mcp-calls.md` — for when this integration lives inside another Claude/Cursor/Codex workflow)

## Rate limit & retry strategy

- Data API: 10 RPS, Project API: 5 RPS. Pace sequentially for batched workflows; small-batch parallelism (≤3 concurrent) is safe.
- 429 handling: exponential backoff with jitter (1s → 2s → 4s → 8s, ±20% jitter). 5xx: same. Treat 403 "Insufficient funds" as terminal — no retry.

## What's running now (live mode only)

{Bullet list of MCP calls that were executed, with their outcomes. Pulled from `evidence/04-execution-log.md`.}

## What you still need to do

{Concrete next steps for the developer. E.g., "Run `python.py` daily via cron at 06:00 UTC", "Open the project at https://online.seranking.com/...", "Add a webhook for rank changes via Settings → Notifications".}

## Linked docs

- {Direct links to the relevant pages on `seranking.com/api/data/*` and `seranking.com/api/project/*`.}

## When to escalate to another skill

- `seo-content-brief` — once your integration is pulling keyword data, this skill turns it into editor briefs.
- `seo-technical-audit` — if the integration involves website audits, this skill interprets the audit output.
- `seo-drift baseline` — if the integration's job is to track a domain over time, snapshot it first.

ヒント

• 1つの API キーですべてを認証できます。 API_TOKEN（ヘッドレスの場合は X-Api-Key ヘッダー）で DATA_* と PROJECT_* の両方を利用できます。Data と Project でキーを分けていた旧方式は廃止されました。後方互換性のため、両方をヘッダーとして渡すこともできますが、現在は X-Api-Key だけで利用できます。references/auth-and-keys.md を参照してください。
• レート制限は IP ごとではなく API キーごとです。 1つのキーを共有するすべてのスレッド／ワーカー／サーバーで、同じ 10-RPS（Data）または 5-RPS（Project）の上限を共有します。本番環境で複数に振り分ける場合は、API Dashboard から複数のキーを発行してください。
• 失敗したリクエストは無料です。 4xx と 5xx ではクレジットを消費しません。通常のエラー再試行に対して、コスト保護を過剰に設計する必要はありません。
• Project API の上限はクレジットではありません。 サブスクリプションの「Sites」「Keywords」「Audit Pages」「AIRT Prompts」の利用枠を消費します。変更を伴う呼び出しでは、プラン上限への影響を事前に明示してください。これらの上限はクレジットよりも制約が強く、上限を引き上げるにはクレジットパックを購入するだけでなく、ユーザーがプランをアップグレードする必要があるためです。
• 変更を行う前に確認してください。 PROJECT_create*、PROJECT_add*、PROJECT_delete*、PROJECT_update*、DATA_create*Audit、DATA_deleteAudit は、いずれもアカウントの状態を永続的に変更します。呼び出す前に、ツール、引数、消費されるものを1行で要約して必ず表示し、y／yes の入力を待ってください。
• 適切な ID 解決ツールを使用してください。 「プロジェクト X／キーワード Y を操作したい」というリクエストのほとんどでは、まず ID の検索が必要です。全項目の一覧については、references/api-surface-map.md の「ID resolution」を参照してください。よくあるケース：
  • プロジェクト ID → PROJECT_listProjects（サブアカウント構成の場合は PROJECT_listOwnedProjects／PROJECT_listSharedProjects）。
  • 順位トラッキング用の検索エンジン → country_code を PROJECT_addSearchEngine に直接渡します（ISO 3166-1 alpha-2）。地域限定の検索エンジン（Catalonia、Turkish-Cypriot Cyprus）の場合に限り、PROJECT_getAvailableSearchEngines を使用してください。
  • SERP の地域 → DATA_getSerpLocations。
  • 言語 → PROJECT_getGoogleLanguages。
  • ローカル順位トラッキング用の地域 → PROJECT_getAvailableRegions（略称は拒否されるため、name フィールドの値をそのまま使用してください）。
• エクスポートでは、ステータスエンドポイントをポーリングしてください。 非同期エンドポイント（/backlinks/export、/keywords/export）はタスク ID を返します。その後の *ExportStatus のポーリングはレート制限の対象ですが、クレジットは消費しません。まずは5秒間隔でポーリングし、タスクが大きい場合は指数バックオフを使用してください。
• ドキュメントを WebFetching する前に、MCP ツールの説明を確認してください。 すべての MCP ツールは、プロトコル経由で完全な入力スキーマ、デフォルト値、使用上の注意を公開しています。たとえば DATA_getDomainCompetitors には、約60KBのレスポンス上限が記載されています。ただし、説明に含まれていない情報が1つあります。クレジットのコストです。コストについては references/rate-limits-and-credits.md と公開されているエンドポイントごとのページを参照してください。
• 大規模なリストを返すエンドポイントでは、MCP のトランスポート上限を超える場合があります。 人気のあるドメインに対する DATA_getDomainCompetitors や、大規模なドメインに対する DATA_getDomainKeywords／DATA_getAllBacklinks は、MCP クライアントのインラインのトークン上限を超えるレスポンスを返すことがあります。その場合、結果は自動的にファイルに保存されます。保存されたファイルに対して jq で範囲を指定して取得するか、REST エンドポイントを直接呼び出してください（生の REST にはサイズ上限がありません）。references/api-surface-map.md を参照してください。
• 「MCP の Swagger／OpenAPI を見せて」というリクエストには、開発者に MCP Inspector（npx @modelcontextprotocol/inspector https://api.seranking.com/mcp）または mcp-scan を案内してください。どちらもライブのツール／プロンプト／リソースのカタログを調べます。標準的な MCP→OpenAPI コンバーターはロードマップにあります。現時点では、Inspector の出力が信頼できる情報源です。

相性のよいツール

• 前提条件： なし — API 統合に関するあらゆる質問の出発点です。
• 後続のツール（統合によってデータが生成される場合）：
  • seo-content-brief — 統合で取得したキーワード調査を編集者向けのブリーフにする場合。
  • seo-page — 統合対象の URL について、維持／更新／統合／削除の判断が必要な場合。
  • seo-drift baseline — 統合の実行開始前にドメインまたは URL のスナップショットを取得し、低下を検出できるようにする場合。
  • seo-technical-audit — 統合に監査の実行が含まれ、出力の優先順位付けが必要な場合。
  • seo-ai-search-share-of-voice — 統合で AIRT の可視性を追跡し、競合分析が必要な場合。

参考資料

• references/auth-and-keys.md — API キーの形式、OAuth とヘッダーの使い分け、ヘッドレス／CI のパターン、キーのローテーション。
• references/rate-limits-and-credits.md — 10 RPS／5 RPS、クレジットの課金モデル、プラン上限の消費、エラーコード（429、403）、指数バックオフのテンプレート。
• references/api-surface-map.md — 完全なルーティング表（各 API の担当範囲）、ID 解決表、「必要なツールはどれか」を判断するための決定木。
• references/integration-patterns.md — すぐにコピー＆ペーストできる、代表的な 5 つのレシピ：ランクトラッカーのセットアップ、被リンクの一括エクスポート、監査パイプライン、AIRT 可視性トラッカー、キーワード調査の一括ジョブ。