座標グリッドで複数地点の回答を一度に比較できます

1つの質問を3×3から9×9の座標グリッドで一度に問い合わせ、地点ごとの回答を返します。GEOモニターもグリッドで実行し、地図で確認できます。

得られる結果

• POST /v1/async/task/gridは、中心点、グリッドのsize(3、5、7、9)、radiusMeters(100〜50,000)を受け取り、地点ごとに1つのタスクを開始します。
• 地点ごとにrow、col、location、タスクが返ります。0行目が北端、0列目が西端です。
• GET /v1/async/task/grid/:idはグリッドと全地点を返し、include=responseを付けると完了した回答も含まれます。
• GEOモニターはlocation(1地点)またはgridを受け取ります。実行数は質問 × エンジン × 地点で最大200件、GET /v1/monitors/:id/gridは地点ごとの回答数、言及、引用、上位の競合を返します。
• payload.locationは{"latitude":37.4979,"longitude":127.0276}のような座標のみ受け付けます。地名は受け付けなくなったため、送信前に座標へ変換してください。

仕組み

各地点は通常のタスクとして実行されるため、ポーリング、Webhook、クレジット、同時実行は単一タスクと同じです。同じidempotencyKeyで再送すると、不足している地点だけが実行されます。ダッシュボードのVisibilityタブのBy locationマップでは、セルを押すとその地点の最新の回答が開きます。

活用例

• 近くのクリニックのような地域の質問で、どの地域がブランドに言及しているかを確認できます。
• 地域ページや掲載情報を変更する前に、同じ質問を都市全体で比較できます。
• グリッドモニターで、表示範囲が時間とともにどう変わるかを追跡できます。

リクエストを送る

質問を1回送り、中心点とグリッドを指定します。payloadのcountryは単一タスクと同じです。

curl -X POST https://api.querying.ai/v1/async/task/grid \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "CHATGPT",
    "payload": {
      "prompt": "recommend a dermatologist nearby",
      "country": "KR"
    },
    "grid": {
      "center": { "latitude": 37.4979, "longitude": 127.0276 },
      "size": 3,
      "radiusMeters": 1500
    },
    "idempotencyKey": "gangnam-derm-2026-10-09"
  }'

レスポンス

呼び出すと200でグリッドと地点ごとの項目が返ります。spacingMetersは隣り合う地点の間隔です。

{
  "success": true,
  "grid": {
    "id": "…",
    "center": { "latitude": 37.4979, "longitude": 127.0276 },
    "size": 3,
    "radiusMeters": 1500,
    "spacingMeters": 1500
  },
  "summary": { "total": 9, "succeeded": 9, "failed": 0 },
  "points": [
    {
      "row": 0,
      "col": 0,
      "location": { "latitude": 37.5114, "longitude": 127.0097 },
      "task": { "id": "…", "status": "PENDING" },
      "credits": 1
    },
    {
      "row": 0,
      "col": 1,
      "location": { "latitude": 37.5114, "longitude": 127.0276 },
      "task": { "id": "…", "status": "PENDING" },
      "credits": 1
    }
  ]
}

グリッドはIDで後から読み取れます。地点ごとにタスクの状態が表示され、include=responseを付けると回答も含まれます。

curl "https://api.querying.ai/v1/async/task/grid/$GRID_ID?include=response" \
  -H "Authorization: Bearer $QUERYING_API_KEY"

エラー

中心点がすべての地点に共通する理由で拒否された場合、グリッド全体が拒否されタスクは作成されません。位置の形式が誤っていると400、位置に対応しないエンジンだと422を返します。

VALIDATION_ERRORHTTP 400

フィールドが欠けているか、範囲外の値です。details に該当するフィールドが入ります。

LOCATION_UNSUPPORTEDHTTP 422

payload.location は CHATGPT、GEMINI、GOOGLE、AIMODE、GOOGLE_SERP で使えます。それ以外のエンジンは送信時にこのコードを返します。

KEY_SCOPE_DENIEDHTTP 403

キーの「許可するエンジン」の対象外のエンジンです。別のキーを使うか、「キーを管理」でエンジンを追加してください。

INSUFFICIENT_CREDITSHTTP 402

残高がタスクの料金を下回っています。クレジットを追加するかプランを上げてから、もう一度送ってください。

料金

各地点は、そのエンジンの単一タスクと同じクレジットがかかります。プランの上限は https://querying.ai/pricing で確認できます。