Compare respostas de vários lugares com uma grade de coordenadas

Uma chamada faz a mesma pergunta em uma grade de coordenadas de 3×3 a 9×9 e devolve as respostas ponto a ponto. Os monitores GEO também podem usar grade e mostrá-la em um mapa.

O que você recebe

• POST /v1/async/task/grid recebe um ponto central, um size de grade de 3, 5, 7 ou 9 e um radiusMeters de 100 a 50.000, e inicia uma tarefa por ponto.
• Cada ponto devolve row, col, location e sua tarefa. A linha 0 é a borda norte e a coluna 0 a borda oeste.
• GET /v1/async/task/grid/:id mostra a grade e todos os pontos; include=response acrescenta as respostas concluídas.
• Um monitor GEO agora aceita location (um ponto) ou grid. As execuções são perguntas × mecanismos × pontos, até 200 tarefas, e GET /v1/monitors/:id/grid devolve respostas, menções, citações e o principal concorrente por ponto.
• payload.location agora aceita apenas coordenadas, como {"latitude":37.4979,"longitude":127.0276}. Nomes de lugares não são mais aceitos; converta os nomes em coordenadas antes de enviar.

Como funciona

Cada ponto roda como uma tarefa comum, então consulta, webhooks, créditos e concorrência funcionam como em uma tarefa única. Reenviar o mesmo idempotencyKey executa apenas os pontos que faltam. Na aba Visibility do painel, o mapa By location abre as respostas mais recentes de um ponto ao clicar na célula.

Onde ajuda

• Ver quais bairros mencionam sua marca em uma pergunta local, como clínicas por perto.
• Comparar a mesma pergunta em uma cidade inteira antes de mudar páginas locais ou fichas.
• Acompanhar a cobertura ao longo do tempo com um monitor de grade.

Envie a requisição

Envie a pergunta uma vez com um ponto central e uma grade. O country de payload continua como em uma tarefa única.

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"
  }'

Resposta

A chamada responde 200 com a grade e uma entrada por ponto. spacingMeters é a distância entre pontos vizinhos.

{
  "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
    }
  ]
}

Leia a grade depois pelo ID. Cada ponto mostra o status da tarefa e, com include=response, sua resposta.

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

Erros

Se o ponto central for recusado por um motivo comum a todos os pontos, a grade inteira é recusada e nenhuma tarefa é criada. Um formato de localização errado devolve 400 e um mecanismo sem suporte a localização devolve 422.

VALIDATION_ERRORHTTP 400

Falta um campo ou o valor está fora do intervalo. details indica o campo.

LOCATION_UNSUPPORTEDHTTP 422

payload.location funciona em CHATGPT, GEMINI, GOOGLE, AIMODE e GOOGLE_SERP. Os outros mecanismos devolvem este código no envio.

KEY_SCOPE_DENIEDHTTP 403

O mecanismo está fora dos Mecanismos permitidos da chave. Use outra chave ou adicione o mecanismo em Gerenciar chave.

INSUFFICIENT_CREDITSHTTP 402

O saldo é menor que o preço da tarefa. Adicione créditos ou mude de plano e envie de novo.

Preço

Cada ponto custa os créditos de uma tarefa única no seu mecanismo. Os limites dos planos estão em https://querying.ai/pricing .