좌표 격자로 여러 지점의 답변을 한 번에 비교해요

질문 하나를 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} 같은 좌표만 받습니다. 장소 이름은 더 이상 받지 않으므로, 제출하기 전에 이름을 좌표로 바꿔 주세요.

동작 방식

지점마다 일반 태스크로 실행되므로 폴링, 웹훅, 크레딧, 동시 실행은 단일 태스크와 같습니다. 같은 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 에서 볼 수 있습니다.