# 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
}
```