用坐标网格一次比较多个地点的回答

一次调用即可在 3×3 到 9×9 的坐标网格上提出同一个问题，并按地点返回回答。GEO 监控也可以按网格运行，并在地图上查看。

获得的结果

• POST /v1/async/task/grid 接收中心点、网格大小 size（3、5、7 或 9）和 radiusMeters（100 到 50,000），并为每个地点启动一个任务。
• 每个地点返回 row、col、location 和任务。第 0 行是北边，第 0 列是西边。
• GET /v1/async/task/grid/:id 返回网格和所有地点，加上 include=response 还会包含已完成的回答。
• GEO 监控现在接受 location（一个地点）或 grid。运行数为问题 × 引擎 × 地点，最多 200 个任务，GET /v1/monitors/:id/grid 按地点返回回答数、提及、引用和排名最高的竞争对手。
• payload.location 现在只接受坐标，例如 {"latitude":37.4979,"longitude":127.0276}。不再接受地名，提交前请先把地名转换为坐标。

工作原理

每个地点都作为普通任务运行，因此轮询、Webhook、积分和并发与单个任务相同。用同一个 idempotencyKey 再次提交时，只会运行缺失的地点。在控制台的 Visibility 标签页中，By location 地图上点击单元格即可打开该地点的最新回答。

应用场景

• 针对附近诊所这类本地问题，查看哪些区域提到了你的品牌。
• 在修改本地页面或商家信息之前，在整个城市范围内比较同一个问题。
• 用网格监控跟踪覆盖范围随时间的变化。

发送请求

只需发送一次问题，并同时指定中心点和网格。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 。