# DataForGEO API
> DataForGEO は 1 つの prompt を複数の AI 検索プロダクトに投げて回答を返し、ブランドごとの GEO 指標（言及・引用・推薦順位など）を計算します。課金は credit 単位です。
- Base URL: https://api.dataforgeo.dev
- Auth: `x-api-key` header (https://dashboard.dataforgeo.dev/keys)
- OpenAPI: https://docs.dataforgeo.dev/openapi.json
- Web 版: https://docs.dataforgeo.dev/

## クイックスタート

すべてのエンドポイントは x-api-key ヘッダー 1 つで認証します。リクエストとレスポンスは JSON、日時はすべて ISO 8601（UTC）です。

| 項目 | 説明 |
| --- | --- |
| Base URL | `https://api.dataforgeo.dev` |
| 認証 | `x-api-key` — コンソールで作成。Pro は 5 個、Scale・Enterprise は無制限 |
| 無料枠 | `100 credits` — 登録時に付与。標準エンジン 100 回分 |

### 最初のリクエスト

```bash
curl https://api.dataforgeo.dev/v1/geo/answer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "东京有哪些适合家庭入住的民宿？",
    "engines": [
      "chatgpt"
    ],
    "brand": "晓宅",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### レスポンス例

```json
{
  "request_id": "req_8f2c1a",
  "prompt": "东京有哪些适合家庭入住的民宿？",
  "credits_used": 1,
  "answers": [
    {
      "engine": "chatgpt",
      "sample": 1,
      "status": "ok",
      "cached": false,
      "generated_at": "2026-11-02T00:31:12Z",
      "text": "……",
      "brand": {
        "mentioned": true,
        "mention_count": 2,
        "first_position": 3,
        "sentiment": "positive"
      },
      "entities": [
        {
          "name": "晓宅",
          "type": "brand",
          "position": 3,
          "is_competitor": false
        },
        {
          "name": "Example Stay",
          "type": "brand",
          "position": 1,
          "is_competitor": true
        }
      ],
      "citations": [
        {
          "url": "https://example.com/guide",
          "domain": "example.com",
          "position": 1,
          "is_brand_domain": false
        }
      ]
    }
  ]
}
```


## MCP・Skills・SDK

HTTP を直接呼ぶほかに、公式のオープンソース接続方法が 3 つあります。AI アシスタント向けの MCP サーバー、エージェント向けの Agent Skills、自分のコード向けの TypeScript / Python SDK です。いずれも環境変数 DATAFORGEO_API_KEY 1 つで動き、課金は API を直接呼ぶ場合と同じです。

| 方法 | 向いている用途 | インストール |
| --- | --- | --- |
| MCP サーバー | Claude や Cursor などの AI アシスタントにクエリ用ツールを追加 | `npx -y @dataforgeo/mcp` |
| Agent Skills | エージェントが診断・競合比較・引用分析・週次レポートをワークフローとして実行 | `/plugin install dataforgeo@dataforgeo` |
| SDK | 自分の TypeScript / Python コードに組み込む | `npm install @dataforgeo/client` |

### MCP サーバー

Claude Code・Claude Desktop・Cursor・Windsurf など MCP 対応の AI アシスタントに 6 つのツールを追加します。stdio 接続で npx から直接起動、Node.js 20 以上が必要です。各ツールの説明に課金ルールが書かれているため、アシスタントは呼び出し前に消費 credits を把握できます。

```bash
claude mcp add dataforgeo -e DATAFORGEO_API_KEY=$DATAFORGEO_API_KEY -- npx -y @dataforgeo/mcp
```

```json
{
  "mcpServers": {
    "dataforgeo": {
      "command": "npx",
      "args": [
        "-y",
        "@dataforgeo/mcp"
      ],
      "env": {
        "DATAFORGEO_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

| tool | API | 説明 | 消費 |
| --- | --- | --- | --- |
| `geo_answer` | POST /v1/geo/answer | 1 つの prompt の複数エンジン回答（言及・引用・競合付き） | API と同じ |
| `geo_index` | POST /v1/geo/index | 同上＋GEO Index KPI（Pro 以上） | API と同じ |
| `geo_index_summary` | GET /v1/geo/index/summary | 実行済み結果の KPI・トレンド・分解 | 0 |
| `get_job` | GET /v1/jobs/{job_id} | 非同期ジョブを取得。wait_seconds で完了まで待機 | 0 |
| `get_account` | GET /v1/account | プラン・残高・今月の使用量 | 0 |
| `estimate_credits` | ローカル計算 | 1 回またはバッチの最大仮押さえ credits を API を呼ばずに見積もり | 0 |

| 環境変数 | 必須 | 説明 |
| --- | --- | --- |
| `DATAFORGEO_API_KEY` | はい | API キー。x-api-key ヘッダーとして送信 |
| `DATAFORGEO_BASE_URL` | いいえ | API のベース URL を上書き |
| `DATAFORGEO_MAX_CREDITS_PER_CALL` | いいえ | 1 回の geo_answer / geo_index が仮押さえできる上限。超えるとローカルで拒否し送信しません。自動エージェントに推奨 |

https://github.com/DataForGEO/mcp

### Agent Skills

Claude Code・Claude.ai、そして Agent Skills に対応した他のエージェント（Codex CLI・Cursor・Gemini CLI など）で使える GEO ワークフローです。credits を使う skill は残高確認と見積もりを行い、同意を得てから一括実行します。各 skill には依存ゼロの CLI dfgeo.py が付属し、Python 3.8+ だけで動きます。

```text
/plugin marketplace add DataForGEO/skills
/plugin install dataforgeo@dataforgeo
```

| skill | 説明 | credits 消費 |
| --- | --- | --- |
| `dataforgeo-api` | 基本：answer / index / summary の単発呼び出し、残高、credits 見積もり、非同期ジョブ | 呼び出しごと |
| `geo-prompt-set-builder` | 意図 × 層 × 言語で追跡する prompt セットを設計し、JSONL 出力とコスト見積もり | なし |
| `geo-visibility-audit` | ブランドの AI 可視性診断：prompt × エンジンを一括実行し、根拠と施策付きレポートを作成 | あり（見積もり後に同意を得てから） |
| `geo-competitor-benchmark` | 競合比較：シェア・オブ・ボイス、トップ推奨率、平均順位、prompt ごとの勝敗 | あり（同上） |
| `geo-citation-audit` | 引用元分析：AI が引用するサイト、自社ソースの引用率、コンテンツ・外部施策・PR のリスト | 既存結果を再利用し追加課金なし |
| `geo-index-report` | GEO Index の週次・月次レポートと固定 tag の週次追跡 | レポートは無料、追跡は呼び出しごと |

Claude.ai / Claude Desktop：リポジトリで python3 scripts/package.py を実行して zip を作り、設定 → 機能 → Skills からアップロードし、コード実行を有効にします。Skills と MCP は併用できます。

https://github.com/DataForGEO/skills

### SDK

TypeScript / JavaScript は @dataforgeo/client、Python は dataforgeo。

```bash
npm install @dataforgeo/client
pip install dataforgeo
```

```ts
import { DataForGEO } from "@dataforgeo/client";

const client = new DataForGEO(); // reads DATAFORGEO_API_KEY
const res = await client.geo.answer({
  prompt: "东京有哪些适合家庭入住的民宿？",
  engines: ["chatgpt"],
  brand: "晓宅",
  location: "JP",
  language: "zh-CN",
});
console.log(res.answers[0].brand?.mentioned, res._meta.creditsRemaining);
```

```python
from dataforgeo import DataForGEO

client = DataForGEO()  # reads DATAFORGEO_API_KEY
res = client.geo.answer(
    prompt="东京有哪些适合家庭入住的民宿？",
    engines=["chatgpt"],
    brand="晓宅",
    location="JP",
    language="zh-CN",
)
print(res["answers"][0]["brand"]["mentioned"], res.meta.credits_remaining)
```

- 2 つの SDK は 1 対 1 で対応し、全エンドポイント・エラーコード・使用量ヘッダー（x-credits-used など）・非同期ジョブ・webhook 署名検証をカバーします。
- リクエストパラメータとレスポンスフィールドは API と同じ（snake_case）で変換しません。
- 429・408・5xx は自動リトライ（エラーは無料）。ネットワークエラーは GET のみリトライし、二重課金を避けるため POST はリトライしません。

https://github.com/DataForGEO/client


## 課金と credits

実際に返された回答にのみ課金します。開始時に「prompt × エンジン × サンプル数」分を仮押さえし、終了後に精算します。credits は買い切りで有効期限はありません。

| 呼び出し | 回答ごとの消費 |
| --- | --- |
| GEO データ・標準エンジン（chatgpt、google-aio、chatgpt-api、perplexity、grok） | 1 |
| GEO データ・高コストエンジン（gemini、gemini-api、claude） | 2 |
| Index 分析（/v1/geo/index が回答ごとに KPI を計算） | +1 |
| キャッシュヒット | 0 |
| エンジンのタイムアウト・失敗・回答なし | 0 |
| 503 engines_unavailable（指定エンジンがすべて利用不可） | 0 |
| /v1/geo/index/summary、/v1/jobs、/v1/account、/v1/status | 0 |

### レスポンスヘッダー

| ヘッダー | 意味 |
| --- | --- |
| `x-credits-used` | このリクエストで実際に消費した credits |
| `x-credits-remaining` | 消費後の残高 |
| `x-cache` | hit・miss・partial（一部の回答のみヒット） |

### キャッシュ

キャッシュキーは prompt + エンジン + 地域 + 言語 + サンプル番号。有効期間 24 時間、アカウント間で共有。fresh: true でキャッシュを使わず通常料金で実行。


## エンジンと地域

engines には以下 8 つの id を指定でき、複数指定も可能です。エンジンごとに個別に課金・返却されます。回答タイプは 2 種類：プロダクト回答は実際のユーザーがその AI プロダクトの画面で見る回答、モデル回答はモデルの API で組み込みの Web 検索を有効にして得た回答です。

| エンジン id | プラットフォーム | 回答タイプ | 回答ごとの消費 |
| --- | --- | --- | --- |
| `chatgpt` | ChatGPT | プロダクト回答 | 1 |
| `gemini` | Gemini | プロダクト回答 | 2 |
| `google-aio` | Google AI Overview | プロダクト回答 | 1 |
| `chatgpt-api` | ChatGPT API | モデル回答 | 1 |
| `gemini-api` | Gemini API | モデル回答 | 2 |
| `claude` | Claude | モデル回答 | 2 |
| `perplexity` | Perplexity | モデル回答 | 1 |
| `grok` | Grok | モデル回答 | 1 |

- プロダクト回答：chatgpt、gemini、google-aio。モデル回答：chatgpt-api、gemini-api、claude、perplexity、grok。
- chatgpt と chatgpt-api、gemini と gemini-api は別のエンジンです。同じ質問でもプロダクト画面と API では回答や引用元が異なることがあり、KPI とトレンドも別々に集計されます。ユーザーが実際に見る内容を知りたいならプロダクト回答、再現性やモデル別の比較が必要ならモデル回答を使ってください。
- エンジンが利用できないときはその回答を失敗として返し、別の回答タイプで代用しません。そのため同じエンジン id のデータは常に同じ基準です。
- location：ISO 3166-1 の 2 文字国コード（JP、US など）。検索結果と AI Overview の地域を決めます。既定は US。
- language：BCP 47 言語タグ（ja、zh-CN、en など）。既定は location から推定。
- google-aio は検索結果に AI Overview が出た場合のみ回答します。出ない場合は status が no_answer で課金されません。


## AI 回答を取得

`POST https://api.dataforgeo.dev/v1/geo/answer` · all plans

1 つの prompt に対する複数エンジンの AI 回答を取得し、ブランド言及・引用元・競合エンティティを付与します。全プランで利用可能。

### パラメータ

| パラメータ | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `prompt` | string | はい | 質問文。最大 2,000 文字 |
| `engines` | string[] | はい | エンジン id の配列。「エンジンと地域」参照 |
| `brand` | string | いいえ | 検出するブランド名。省略時は回答とエンティティのみ |
| `brand_variants` | string[] | いいえ | ブランドの別名（カタカナ、英語名など） |
| `competitors` | string[] | いいえ | 競合名。最大 20 個 |
| `location` | string | いいえ | 国コード。既定 US |
| `language` | string | いいえ | 言語タグ。既定は location から推定 |
| `samples` | integer | いいえ | エンジンごとのサンプル数。1〜10、既定 1 |
| `fresh` | boolean | いいえ | true でキャッシュを使わない。既定 false |
| `async` | boolean | いいえ | true で job_id を即時返却。「非同期ジョブ」参照 |
| `webhook_url` | string | いいえ | 非同期完了時のコールバック URL |

### リクエスト例

```bash
curl https://api.dataforgeo.dev/v1/geo/answer \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "东京有哪些适合家庭入住的民宿？",
    "engines": [
      "chatgpt"
    ],
    "brand": "晓宅",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### レスポンス例

```json
{
  "request_id": "req_8f2c1a",
  "prompt": "东京有哪些适合家庭入住的民宿？",
  "credits_used": 1,
  "answers": [
    {
      "engine": "chatgpt",
      "sample": 1,
      "status": "ok",
      "cached": false,
      "generated_at": "2026-11-02T00:31:12Z",
      "text": "……",
      "brand": {
        "mentioned": true,
        "mention_count": 2,
        "first_position": 3,
        "sentiment": "positive"
      },
      "entities": [
        {
          "name": "晓宅",
          "type": "brand",
          "position": 3,
          "is_competitor": false
        },
        {
          "name": "Example Stay",
          "type": "brand",
          "position": 1,
          "is_competitor": true
        }
      ],
      "citations": [
        {
          "url": "https://example.com/guide",
          "domain": "example.com",
          "position": 1,
          "is_brand_domain": false
        }
      ]
    }
  ]
}
```

- status は ok・no_answer・timeout・failed。後の 3 つは無料。
- status が timeout または failed のとき、回答に理由を示す error フィールドが付きます（値は下表）。ok と no_answer の回答には付きません。
- first_position は回答の推薦リストでブランドが最初に登場する順位。登場しない場合は null。

### 回答の error フィールド

| error | 意味 |
| --- | --- |
| `upstream_timeout` | 制限時間内にエンジンが回答しなかった（自動リトライ込み） |
| `upstream_error` | エンジンがエラーを返し、自動リトライ後も失敗した |
| `engine_unavailable` | エンジンが一時的に利用できず、呼び出しを行わなかった。/v1/status で状態を確認できます |

### 失敗した回答の例

```json
{
  "engine": "grok",
  "sample": 1,
  "status": "failed",
  "error": "engine_unavailable",
  "cached": false
}
```


## GEO Index を計算

`POST https://api.dataforgeo.dev/v1/geo/index` · Pro / Scale / Enterprise

/v1/geo/answer の結果から GEO Index の KPI を計算します。Pro・Scale・Enterprise で利用可能。Starter は 403 plan_not_allowed。

### パラメータ

/v1/geo/answer と同じパラメータで brand が必須。追加パラメータ：

| パラメータ | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `brand` | string | はい | KPI を計算するブランド |
| `tag` | string | いいえ | 任意のグループタグ（例：osaka-family-q4）。/summary はこれで集計 |
| `intent` | string | いいえ | prompt の意図：compare、cost、discover、evaluate、howto、recommend |
| `persona` | string | いいえ | 質問者像（自由記述）。例：子連れの家族 |

### リクエスト例

```bash
curl https://api.dataforgeo.dev/v1/geo/index \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "prompt": "大阪带孩子住哪里方便？",
    "engines": [
      "chatgpt",
      "perplexity",
      "grok"
    ],
    "brand": "晓宅",
    "tag": "osaka-family-q4",
    "intent": "recommend",
    "persona": "带孩子的家庭",
    "location": "JP",
    "language": "zh-CN"
  }'
```

### レスポンス例

```json
{
  "request_id": "req_91d0b3",
  "brand": "晓宅",
  "tag": "osaka-family-q4",
  "credits_used": 6,
  "answers": [
    "…与 /v1/geo/answer 相同…"
  ],
  "kpis": {
    "visibility": {
      "value": 0.667,
      "numerator": 2,
      "denominator": 3,
      "samples": 3
    },
    "share_of_voice": {
      "value": 0.25,
      "numerator": 2,
      "denominator": 8,
      "samples": 3
    },
    "top_rate": {
      "value": 0,
      "numerator": 0,
      "denominator": 3,
      "samples": 3
    },
    "competitor_gap": {
      "value": -1.33,
      "samples": 3
    },
    "positive_ratio": {
      "value": 1,
      "numerator": 2,
      "denominator": 2,
      "samples": 3
    }
  },
  "kpi_tier": "pro"
}
```

- 上の例は標準エンジン 3 つ × 回答 1 件：3 × 1 credit + Index 3 × 1 credit = 6 credits。
- kpi_tier が pro ならコア KPI のみ、scale なら全 KPI を返します。
- 単発リクエストはサンプルが少なく KPI は参考値です。トレンドや比較には /v1/geo/index/summary を使ってください。


## Index 集計とトレンド

`GET https://api.dataforgeo.dev/v1/geo/index/summary` · Pro / Scale / Enterprise

アカウント内で実行済みの /v1/geo/index 結果を期間で集計し、KPI とトレンドを返します。新たな AI 呼び出しはなく無料。Pro は全体とトレンド、group_by による分解は Scale・Enterprise のみ。

### パラメータ

| パラメータ | 型 | 必須 | 説明 |
| --- | --- | --- | --- |
| `brand` | string | はい | ブランド名。index リクエストと同じ値 |
| `tag` | string | いいえ | このタグのリクエストのみ集計 |
| `from / to` | string | いいえ | 期間（ISO 8601）。既定は直近 30 日 |
| `interval` | string | いいえ | トレンド粒度：day、week、month。既定 week |
| `engines` | string | いいえ | カンマ区切りで対象エンジンを指定 |
| `kpis` | string | いいえ | カンマ区切りで返す KPI を指定。既定はプランの全 KPI |
| `group_by` | string | いいえ | engine・intent・persona・prompt のいずれか 1 つ。Scale のみ (Scale) |

### リクエスト例

```bash
curl "https://api.dataforgeo.dev/v1/geo/index/summary?brand=晓宅&tag=osaka-family-q4&interval=week&group_by=engine" \
  -H "x-api-key: YOUR_API_KEY"
```

### レスポンス例

```json
{
  "brand": "晓宅",
  "window": {
    "from": "2026-10-03T00:00:00Z",
    "to": "2026-11-02T00:00:00Z"
  },
  "answers_counted": 498,
  "kpis": {
    "findability": {
      "value": 42.1
    },
    "visibility": {
      "value": 0.262,
      "numerator": 130,
      "denominator": 498
    }
  },
  "series": [
    {
      "period": "2026-10-05",
      "visibility": 0.255,
      "share_of_voice": 0.018
    },
    {
      "period": "2026-10-12",
      "visibility": 0.263,
      "share_of_voice": 0.026
    }
  ],
  "groups": [
    {
      "key": "chatgpt",
      "answers_counted": 166,
      "kpis": {
        "visibility": {
          "value": 0.301
        }
      }
    },
    {
      "key": "gemini",
      "answers_counted": 166,
      "kpis": {
        "visibility": {
          "value": 0.241
        }
      }
    }
  ]
}
```

- 一部の KPI は集計でのみ提供されます（knowledge_half_life、category_capture_gap など）。
- 集計は自アカウントの index 結果のみを使います。アカウント間で共有されるのは回答キャッシュだけです。


## 非同期ジョブとアカウント

複数エンジン・複数サンプルのリクエストは 1〜2 分かかることがあります。async: true を指定すると job_id が即時に返り、ポーリングか webhook で結果を取得できます。同期リクエストは 120 秒を超えると自動で非同期になり 202 を返します。

### エンドポイント

| エンドポイント | 説明 | credits |
| --- | --- | --- |
| `GET /v1/jobs/{job_id}` | ジョブの状態と結果 | 0 |
| `GET /v1/account` | 残高・プラン・今月の利用量 | 0 |

### 非同期レスポンス

```json
{
  "job_id": "job_3b7e90",
  "status": "queued",
  "credits_held": 9
}
```

`GET /v1/account`

```json
{
  "plan": "scale",
  "credits_remaining": 10422,
  "credits_used_this_month": 1578
}
```

- status は queued → running → completed または failed。completed 時の result は同期レスポンスと同じです。
- 非同期リクエストでは timeout・failed の回答を約 2 分後にもう 1 度実行し、それでも失敗した場合に確定します。同期リクエストでは再実行しません。
- credits_held は仮押さえ分。実際に返った回答で精算し、余りは返却されます。
- webhook_url を指定すると完了時に全結果を POST します。x-dataforgeo-signature ヘッダー（HMAC-SHA256、鍵はコンソール）で送信元を検証できます。
- ジョブ結果は 7 日間保持されます。


## エンジンの状態

`GET https://api.dataforgeo.dev/v1/status` · public, no auth

各エンジンの現在の状態、直近 24 時間の成功率と中央値レイテンシ、直近 30 日の日別可用率を返します。認証不要・無料なので、リクエスト前に使えるエンジンを確認できます。公式サイトのステータスページも同じデータを使っています。

### リクエスト例

```bash
curl "https://api.dataforgeo.dev/v1/status"
```

### レスポンス例

```json
{
  "updated_at": "2026-11-02T05:40:00Z",
  "status": "degraded",
  "engines": [
    {
      "id": "chatgpt",
      "name": "ChatGPT",
      "answer_type": "product",
      "status": "operational",
      "last_24h": {
        "success_rate": 0.987,
        "median_latency_ms": 21400,
        "calls": 1234
      },
      "daily": [
        {
          "date": "2026-10-04",
          "uptime": 0.998
        },
        "… 30 项 …",
        {
          "date": "2026-11-02",
          "uptime": 1
        }
      ]
    },
    {
      "id": "claude",
      "name": "Claude",
      "answer_type": "model",
      "status": "degraded",
      "last_24h": {
        "success_rate": 0.912,
        "median_latency_ms": 9800,
        "calls": 640
      },
      "daily": [
        "…"
      ]
    },
    {
      "id": "grok",
      "name": "Grok",
      "answer_type": "model",
      "status": "unavailable",
      "last_24h": {
        "success_rate": 0.64,
        "median_latency_ms": 7300,
        "calls": 210
      },
      "daily": [
        "…"
      ]
    },
    "…"
  ]
}
```

### engines[].status の値

| status | 意味 |
| --- | --- |
| `operational` | 正常 |
| `degraded` | 低下：直近 15 分間の成功率が 90% 未満。リクエストは送られますが失敗が増える可能性があります |
| `unavailable` | 利用不可：このエンジンの回答は failed / engine_unavailable で返り、課金されません |

- トップレベルの status は全エンジンの集約です。すべて unavailable なら outage、いずれかが degraded か unavailable なら degraded、それ以外は operational。
- last_24h は直近 24 時間の実呼び出しを集計します。success_rate は 0〜1 の小数、median_latency_ms は中央値レイテンシ、calls は呼び出し回数。呼び出しがなければ前の 2 つは null。google-aio の no_answer は成功扱い、キャッシュヒットは含みません。
- daily は UTC 日付で常に 30 件、古い順で最後が今日です。呼び出しがない日の uptime は null。
- 認証不要・CORS *・レスポンスは 30 秒キャッシュ。データは 5 分ごとに集計されます。Web 版は dataforgeo.dev/status。


## KPI フィールド一覧

Pro はコア KPI 11 個、Scale・Enterprise は上位 KPI 8 個を追加で返します。公開定義のみで計算式は非公開です。

| フィールド | 名称 | 定義 | 単位 | プラン | 返却箇所 |
| --- | --- | --- | --- | --- | --- |
| `findability` | 総合発見度 | AI 回答でブランドが見つかり推薦される度合いの総合スコア | スコア | pro | 単発と集計 |
| `visibility` | 可視性 | ブランドが登場する回答の割合 | 比率 | pro | 単発と集計 |
| `own_mentions` | 自社言及数 | 回答あたりの平均ブランド言及数 | 回 | pro | 単発と集計 |
| `citations` | 引用数 | 回答あたりの平均引用元数 | 回 | pro | 単発と集計 |
| `citation_rate` | 引用率 | 自社ソースを引用した回答の割合 | 比率 | pro | 単発と集計 |
| `share_of_voice` | シェア・オブ・ボイス | ブランド＋競合の言及に占めるブランド言及の割合 | 比率 | pro | 単発と集計 |
| `competitor_mentions` | 競合言及数 | 回答あたりの平均競合言及数 | 回 | pro | 単発と集計 |
| `competitor_gap` | 競合差 | 自社言及数 − 競合言及数 | 回 | pro | 単発と集計 |
| `top_rate` | 首位推薦率 | ブランドが推薦 1 位の回答の割合 | 比率 | pro | 単発と集計 |
| `positive_ratio` | ポジティブ比率 | ブランド言及のうちポジティブな割合 | 比率 | pro | 単発と集計 |
| `tone` | トーン | ブランド言及時の全体的なトーン（−1〜1） | スコア | pro | 単発と集計 |
| `weighted_share` | 加重シェア | 言及位置で加重したシェア・オブ・ボイス | 比率 | scale | 集計のみ |
| `rank_gap` | 順位差 | 各競合との推薦順位差（競合ごと） | 位 | scale | 単発と集計 |
| `recommendation_position` | 推薦順位指数 | 推薦リスト内の位置スコア | スコア | scale | 単発と集計 |
| `purchase_intent_rate` | 購買意向推薦率 | 購買意向の質問でブランドが推薦される割合 | 比率 | scale | 単発と集計 |
| `conclusion_bias` | 結論推薦傾向 | 回答の結論が推薦か否定か（−1〜1） | スコア | scale | 単発と集計 |
| `category_capture_gap` | カテゴリ獲得差 | 所属カテゴリの質問での獲得差 | スコア | scale | 集計のみ |
| `knowledge_half_life` | AI 知識半減期 | AI のブランド認知が減衰する周期 | 週 | scale | 集計のみ |
| `features` | 特徴言及 | 回答で言及されたブランドの訴求点 | リスト | scale | 単発と集計 |

- 比率フィールドは 0〜1。numerator と denominator を持つものはそのまま検算できます。
- purchase_intent_rate は購買意向の prompt のみを集計するため、intent の指定が必要です。


## エラーと制限

エラーは共通の形式で返り、課金されません。1 エンジンの失敗でリクエスト全体は失敗せず、その回答の status が timeout または failed になり error フィールドに理由が入ります（無料）。他のエンジンは通常どおり返ります。指定したエンジンがすべて利用不可の場合のみ、リクエスト全体が 503 になります。

| HTTP | code | 意味 |
| --- | --- | --- |
| 400 | `invalid_request` | パラメータ不足または形式不正。message に該当フィールド |
| 400 | `unsupported_engine` | engines に不明なエンジン id |
| 401 | `invalid_api_key` | API キーがない・誤り・無効化済み |
| 402 | `insufficient_credits` | 残高が仮押さえ分に足りない |
| 403 | `plan_not_allowed` | 現在のプランでは使えない（Starter の index、Pro の group_by など） |
| 404 | `not_found` | job_id が存在しないか期限切れ |
| 500 | `internal_error` | サーバーエラー。request_id を添えてサポートへ |
| 503 | `engines_unavailable` | 指定したエンジンがすべて一時的に利用不可。Retry-After（秒）付きで返り、仮押さえ・課金はありません。1 つでも利用可能なら通常どおり処理します |

```json
{
  "error": {
    "code": "insufficient_credits",
    "message": "本次请求需预占 9 credits，余额 4",
    "request_id": "req_7a11c2"
  }
}
```

```json
{
  "error": {
    "code": "engines_unavailable",
    "message": "请求的引擎当前都不可用：claude、grok",
    "request_id": "req_5c02e4"
  }
}
```

### 制限

- アカウント単位のレート制限はありません。安定のため同時実行は 100 未満を推奨（負荷試験で確定予定）。
- 1 リクエストあたり最大 8 エンジン × 10 サンプル = 80 回答。
- エンジンの一時的なエラー（ネットワーク、タイムアウト、レート制限、5xx）は制限時間内で最大 2 回自動リトライします。追加課金はありません。
- prompt は最大 2,000 文字、competitors は最大 20 個。
- キャッシュは 24 時間、非同期ジョブ結果は 7 日間保持。