Comparez les réponses de plusieurs lieux avec une grille de coordonnées

Un seul appel pose la même question sur une grille de coordonnées de 3×3 à 9×9 et renvoie les réponses point par point. Les moniteurs GEO peuvent aussi utiliser une grille et l’afficher sur une carte.

Ce que vous obtenez

• POST /v1/async/task/grid prend un point central, une grille size de 3, 5, 7 ou 9 et un radiusMeters de 100 à 50 000, puis lance une tâche par point.
• Chaque point renvoie row, col, location et sa tâche. La ligne 0 est le bord nord et la colonne 0 le bord ouest.
• GET /v1/async/task/grid/:id affiche la grille et tous les points ; include=response ajoute les réponses terminées.
• Un moniteur GEO accepte désormais location (un point) ou grid. Les exécutions valent questions × moteurs × points, jusqu’à 200 tâches, et GET /v1/monitors/:id/grid renvoie réponses, mentions, citations et principal concurrent par point.
• payload.location n’accepte plus que des coordonnées, comme {"latitude":37.4979,"longitude":127.0276}. Les noms de lieux ne sont plus acceptés : convertissez-les en coordonnées avant l’envoi.

Fonctionnement

Chaque point s’exécute comme une tâche ordinaire : interrogation, webhooks, crédits et concurrence fonctionnent comme pour une tâche seule. Renvoyer le même idempotencyKey n’exécute que les points manquants. Dans l’onglet Visibility du tableau de bord, la carte By location ouvre les dernières réponses d’un point lorsque vous cliquez sur sa cellule.

Cas d’usage

• Voir quels quartiers mentionnent votre marque pour une question locale comme des cliniques à proximité.
• Comparer la même question sur toute une ville avant de modifier des pages locales ou des fiches.
• Suivre la couverture dans le temps avec un moniteur de grille.

Envoyer la requête

Envoyez la question une seule fois avec un point central et une grille. Le country de payload reste identique à celui d’une tâche seule.

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

Réponse

L’appel répond 200 avec la grille et une entrée par point. spacingMeters est la distance entre points voisins.

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

Relisez la grille plus tard avec son identifiant. Chaque point indique le statut de sa tâche et, avec include=response, sa réponse.

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

Erreurs

Si le point central est refusé pour une raison commune à tous les points, toute la grille est refusée et aucune tâche n’est créée. Un format de position incorrect renvoie 400, et un moteur sans prise en charge de la position renvoie 422.

VALIDATION_ERRORHTTP 400

Un champ manque ou sort des valeurs admises. details indique le champ.

LOCATION_UNSUPPORTEDHTTP 422

payload.location fonctionne avec CHATGPT, GEMINI, GOOGLE, AIMODE et GOOGLE_SERP. Les autres moteurs renvoient ce code dès l’envoi.

KEY_SCOPE_DENIEDHTTP 403

Le moteur est hors des Moteurs autorisés de la clé. Utilisez une autre clé ou ajoutez le moteur dans Gérer la clé.

INSUFFICIENT_CREDITSHTTP 402

Le solde est inférieur au prix de la tâche. Ajoutez des crédits ou changez de plan, puis renvoyez-la.

Tarif

Chaque point coûte les crédits d’une tâche seule sur son moteur. Les limites des forfaits figurent sur https://querying.ai/pricing .