Neu: Google Places

Erhalten Sie die Orte, die Googles Places-Tab für eine Suche in der Stadt Ihrer Wahl zeigt, bis zu 100, mit Adresse, Koordinaten, Telefon, Website und Bewertung, für 1 Credit pro 20 Orte.

Was Sie erhalten

• GOOGLE_PLACES: Jede Aufgabe liest die Liste, die Googles Places-Tab für Ihre Suche aus der gewählten Stadt zeigt, bis zu 100 Orte.
• places: jeder Ort mit name, position und der page, von der er stammt, dazu location (Adresse, Breiten- und Längengrad), phoneNumber, url, mapsUrl, placeId, reviews mit Bewertung und Anzahl, category und dem Rezensionszitat, das Google zeigt.
• pages: wie viele Seiten mit je 20 Orten die Aufgabe gelesen hat, die Zahl, nach der abgerechnet wird.

So funktioniert es

Senden Sie query und city, die Stadt so geschrieben, wie Google sie nennt, etwa Reno, Nevada, United States. Speichert Ihr Rank-Tracker bereits Googles uule-Wert für einen Ort, senden Sie ihn als uule, und Google sucht von diesem Ort aus. country legt den Markt fest, standardmäßig US.

Google zeigt 20 Orte pro Seite. limit legt fest, wie viele Sie möchten, 1 bis 100 (Standard 20), und die Aufgabe liest bis zu fünf Seiten in Googles Reihenfolge. position zählt über Seiten hinweg weiter, und ein Ort, den Google auf einer späteren Seite wiederholt, zählt einmal. Endet Googles Liste vor Ihrem Limit, erhalten Sie alle Orte, die sie enthielt.

Die Aufgabe prüft auf jeder Seite den Ort, von dem aus Google gesucht hat, sodass alle Orte einer Liste aus derselben Stadt stammen.

Einsatzbereiche

• Verfolgen Sie, auf welchem Platz Ihr Unternehmen unter allen Orten steht, die Google für Ihre Kategorie in Ihrer Stadt zeigt, über die drei Orte des Local Packs hinaus.
• Senden Sie dieselbe Suche in jeder Stadt, in der Sie tätig sind, und vergleichen Sie, wer in jedem Markt vorn liegt.
• Stellen Sie die Ortsliste neben die Antworten von Google AI Overview und AI Mode auf dieselbe Suche und sehen Sie, welche Orte die Antworten empfehlen.
• Probieren Sie es im Playground aus: Wählen Sie im Suche-Tab Google Places, geben Sie eine Stadt ein und wählen Sie bis zu 100 Orte.

Anfrage senden

Senden Sie die Anfrage mit Ihrem API-Schlüssel im Header Authorization.

curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "GOOGLE_PLACES",
    "payload": {
      "query": "Reno attorney",
      "city": "Reno, Nevada, United States",
      "limit": 100,
      "country": "US"
    }
  }'

Felder der Anfrage

taskTypestringPflicht

Die Engine, die die Aufgabe ausführt, etwa CHATGPT oder GOOGLE.

payload.querystringPflicht

Die Suchanfrage, so formuliert, wie ein Nutzer sie ins Suchfeld tippt.

payload.citystring

Die Stadt, aus der gesucht wird, so geschrieben, wie Google sie nennt, etwa Reno, Nevada, United States. Bis zu 100 Zeichen. Eine Aufgabe nutzt city oder uule.

payload.uulestring

Googles Standortwert in seiner w+-Form, den Rank-Tracker für jeden Ort speichern. Er geht unverändert an Google.

payload.limitinteger

Anzahl der zurückgegebenen Orte, 1 bis 100. Standardwert 20, eine Seite von Googles Liste.

payload.countrystring

Zweistelliger Ländercode des Markts, aus dem gefragt wird, etwa US, KR oder JP. Standard US.

webhook.urlstring

Eine HTTPS-Adresse Ihres Servers. Die fertige Aufgabe wird dorthin gesendet, sobald sie abgeschlossen ist.

Antwort

So sieht eine fertige Aufgabe aus, für die Lesbarkeit gekürzt.

{
  "success": true,
  "task": {
    "id": "…",
    "taskType": "GOOGLE_PLACES",
    "status": "COMPLETED",
    "createdAt": "…"
  },
  "credits": { "creditsToCharge": 5, "creditsCharged": 5 },
  "response": {
    "places": [
      {
        "name": "Joey Gilbert Law",
        "position": 1,
        "placeId": "ChIJcW7HSupAmYARRnrM6Ap0UtU",
        "location": {
          "address": "405 Marsh Ave, Reno, NV 89509",
          "latitude": 39.519216,
          "longitude": -119.815709
        },
        "phoneNumber": "(775) 210-1501",
        "url": "https://joeygilbertlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=15371476068373133894",
        "reviews": [
          { "rating": 4.4, "count": 381, "providerName": "Google" }
        ],
        "category": "Criminal justice attorney",
        "snippet": "Joey is knowledgeable, straightforward, and fights hard for his clients.",
        "page": 1
      },
      {
        "name": "Viloria, Oliphant, Oster & Aman L.L.P.",
        "position": 2,
        "placeId": "ChIJv8KkdMlAmYARmINKFMPLxbs",
        "location": {
          "address": "327 California Ave, Reno, NV 89509",
          "latitude": 39.520335,
          "longitude": -119.81519
        },
        "phoneNumber": "(775) 515-8480",
        "url": "https://www.renonvlaw.com/",
        "mapsUrl": "https://maps.google.com/?cid=13530444694224012184",
        "reviews": [
          { "rating": 4.6, "count": 117, "providerName": "Google" }
        ],
        "category": "Personal injury attorney",
        "snippet": "Tom’s work ethic and knowledge of the legal system is beyond reproach.",
        "page": 1
      },
      "…"
    ],
    "pages": 5,
    "city": "Reno, Nevada, United States"
  }
}

task.statusstring

QUEUED, PROCESSING, dann COMPLETED mit der Antwort oder FAILED mit error.

credits.creditsChargedinteger

Für die fertige Aufgabe berechnete Credits. Eine fehlgeschlagene Aufgabe kostet 0.

response.placesarray

Die Orte in Googles Reihenfolge: name, position über Seiten hinweg gezählt, die page, von der ein Ort stammt, und placeId, location, phoneNumber, url, mapsUrl, reviews, category und snippet, wenn Google sie zeigt.

response.pagesinteger

Gelesene Seiten mit je 20 Orten, 1 bis 5. Die Aufgabe wird nach diesen Seiten berechnet.

Ergebnis abholen

Die Anfrage liefert sofort die Aufgabe mit status QUEUED. Fragen Sie GET /v1/async/task/{id} ab, bis status COMPLETED oder FAILED ist, oder geben Sie webhook.url an, dann kommt die fertige Aufgabe mit denselben task, credits und response auf Ihrem Server an. Ergebnisse bleiben 24 Stunden nach Abschluss abrufbar.

curl https://api.querying.ai/v1/async/task/$TASK_ID \
  -H "Authorization: Bearer $QUERYING_API_KEY"

Fehler

VALIDATION_ERRORHTTP 422

limit liegt außerhalb von 1 bis 100, city ist leer oder länger als 100 Zeichen, oder city wurde zusammen mit uule oder location gesendet. details nennt das Feld.

MISSING_API_KEYHTTP 401

Der Header Authorization fehlt, oder sein Schlüssel ist unbekannt, abgelaufen oder widerrufen.

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

Jede Seite mit 20 Orten kostet 1 Credit, 100 Orte kosten also 5 Credits. Beim Senden werden die Credits reserviert, die Ihr limit braucht, und beim Abschluss werden die gelesenen Seiten berechnet: Eine Liste, die auf Seite 2 endet, kostet 2 Credits.