Compara respuestas de varios lugares con una cuadrícula de coordenadas

Una llamada hace la misma pregunta en una cuadrícula de coordenadas de 3×3 a 9×9 y devuelve las respuestas punto por punto. Los monitores GEO también pueden usar una cuadrícula y mostrarla en un mapa.

Qué obtienes

• POST /v1/async/task/grid recibe un punto central, un size de cuadrícula de 3, 5, 7 o 9 y un radiusMeters de 100 a 50.000, y inicia una tarea por punto.
• Cada punto devuelve row, col, location y su tarea. La fila 0 es el borde norte y la columna 0 el borde oeste.
• GET /v1/async/task/grid/:id muestra la cuadrícula y todos los puntos; include=response añade las respuestas terminadas.
• Un monitor GEO ahora acepta location (un punto) o grid. Las ejecuciones son preguntas × motores × puntos, hasta 200 tareas, y GET /v1/monitors/:id/grid devuelve respuestas, menciones, citas y el competidor principal por punto.
• payload.location ahora solo acepta coordenadas, como {"latitude":37.4979,"longitude":127.0276}. Ya no se aceptan nombres de lugar, así que conviértelos a coordenadas antes de enviar.

Cómo funciona

Cada punto se ejecuta como una tarea normal, así que el sondeo, los webhooks, los créditos y la concurrencia funcionan igual que en una tarea individual. Si vuelves a enviar el mismo idempotencyKey, solo se ejecutan los puntos que faltan. En la pestaña Visibility del panel, el mapa By location abre las últimas respuestas de un punto al pulsar su celda.

Para qué sirve

• Ver qué barrios mencionan tu marca en una pregunta local, como clínicas cercanas.
• Comparar la misma pregunta en toda una ciudad antes de cambiar páginas locales o fichas.
• Seguir la cobertura en el tiempo con un monitor de cuadrícula.

Envía la solicitud

Envía la pregunta una vez con un punto central y una cuadrícula. El country de payload se indica igual que en una tarea individual.

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

Respuesta

La llamada responde 200 con la cuadrícula y una entrada por punto. spacingMeters es la distancia entre puntos vecinos.

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

Lee la cuadrícula más tarde por su ID. Cada punto muestra el estado de su tarea y, con include=response, su respuesta.

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

Errores

Si el punto central se rechaza por un motivo común a todos los puntos, se rechaza toda la cuadrícula y no se crea ninguna tarea. Un formato de ubicación incorrecto devuelve 400 y un motor sin soporte de ubicación devuelve 422.

VALIDATION_ERRORHTTP 400

Falta un campo o su valor está fuera de rango. details indica el campo.

LOCATION_UNSUPPORTEDHTTP 422

payload.location funciona en CHATGPT, GEMINI, GOOGLE, AIMODE y GOOGLE_SERP. Los demás motores devuelven este código al enviar.

KEY_SCOPE_DENIEDHTTP 403

El motor queda fuera de los Motores permitidos de la clave. Usa otra clave o añade el motor en Gestionar clave.

INSUFFICIENT_CREDITSHTTP 402

El saldo es menor que el precio de la tarea. Añade créditos o mejora el plan y vuelve a enviarla.

Precio

Cada punto cuesta los créditos de una tarea individual en su motor. Los límites de cada plan están en https://querying.ai/pricing .