Antworten an mehreren Orten mit einem Koordinatenraster vergleichen

Ein Aufruf stellt dieselbe Frage auf einem Koordinatenraster von 3×3 bis 9×9 und liefert die Antworten pro Punkt. GEO-Monitore können ebenfalls ein Raster nutzen und es auf einer Karte zeigen.

Was Sie erhalten

• POST /v1/async/task/grid nimmt einen Mittelpunkt, eine Rastergröße size von 3, 5, 7 oder 9 und einen radiusMeters von 100 bis 50.000 entgegen und startet eine Aufgabe pro Punkt.
• Jeder Punkt liefert row, col, location und seine Aufgabe. Zeile 0 ist der Nordrand, Spalte 0 der Westrand.
• GET /v1/async/task/grid/:id zeigt das Raster und alle Punkte; include=response fügt fertige Antworten hinzu.
• Ein GEO-Monitor akzeptiert jetzt location (ein Punkt) oder grid. Die Läufe ergeben sich aus Fragen × Engines × Punkten, höchstens 200 Aufgaben, und GET /v1/monitors/:id/grid liefert pro Punkt Antworten, Erwähnungen, Zitate und den stärksten Wettbewerber.
• payload.location akzeptiert nur noch Koordinaten wie {"latitude":37.4979,"longitude":127.0276}. Ortsnamen werden nicht mehr akzeptiert; wandeln Sie Namen vor dem Senden in Koordinaten um.

So funktioniert es

Jeder Punkt läuft als gewöhnliche Aufgabe, daher funktionieren Polling, Webhooks, Credits und Parallelität wie bei einer einzelnen Aufgabe. Wird derselbe idempotencyKey erneut gesendet, laufen nur die fehlenden Punkte. Im Tab Visibility des Dashboards öffnet die Karte By location per Klick auf eine Zelle die neuesten Antworten dieses Punkts.

Einsatzbereiche

• Sehen, welche Stadtteile Ihre Marke bei einer lokalen Frage wie Kliniken in der Nähe nennen.
• Dieselbe Frage in einer ganzen Stadt vergleichen, bevor Sie lokale Seiten oder Einträge ändern.
• Die Abdeckung mit einem Raster-Monitor über die Zeit verfolgen.

Anfrage senden

Senden Sie die Frage einmal mit Mittelpunkt und Raster. Das country in payload bleibt wie bei einer einzelnen Aufgabe.

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

Antwort

Der Aufruf antwortet mit 200 und liefert das Raster mit einem Eintrag je Punkt. spacingMeters ist der Abstand benachbarter Punkte.

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

Lesen Sie das Raster später über seine ID. Jeder Punkt zeigt den Aufgabenstatus und mit include=response seine Antwort.

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

Fehler

Wird der Mittelpunkt aus einem für alle Punkte gleichen Grund abgelehnt, wird das ganze Raster abgelehnt und keine Aufgabe angelegt. Ein falsches Positionsformat liefert 400, eine Engine ohne Positionsunterstützung 422.

VALIDATION_ERRORHTTP 400

Ein Feld fehlt oder liegt außerhalb des erlaubten Bereichs. details nennt das Feld.

LOCATION_UNSUPPORTEDHTTP 422

payload.location gilt für CHATGPT, GEMINI, GOOGLE, AIMODE und GOOGLE_SERP. Andere Engines liefern diesen Code beim Senden.

KEY_SCOPE_DENIEDHTTP 403

Die Engine liegt außerhalb der Erlaubten Engines des Schlüssels. Nutzen Sie einen anderen Schlüssel oder ergänzen Sie die Engine unter Schlüssel verwalten.

INSUFFICIENT_CREDITSHTTP 402

Das Guthaben liegt unter dem Preis der Aufgabe. Laden Sie Credits auf oder wechseln Sie den Plan und senden Sie erneut.

Preis

Jeder Punkt kostet die Credits einer einzelnen Aufgabe auf seiner Engine. Die Plangrenzen stehen unter https://querying.ai/pricing .