Listings APIListings API
Anmelden

Eintragsstatus prüfen und Live-Links abrufen

Prüfen Sie je Standort Plattform-Sync und Sprachassistenten, sammeln Sie Live-URLs und fassen Sie die Abdeckung zusammen. Webhooks statt Polling.

Sobald ein Standort existiert, wird automatisch ein Eintrag pro Plattform in Ihrem Tarif eingereicht. Diese Anleitung zeigt Ihnen, wie Sie den aktuellen Status jedes Eintrags auslesen, die URLs der veröffentlichten Einträge abrufen und die wiederholten Abfragen beenden, sobald Webhooks eingerichtet sind.

1. Premium-Einträge für einen Standort abrufen

GET /locations/{locationId}/listings/premium gibt einen Datensatz pro Premium-Plattform im Tarif zurück. Das Ergebnis ist ein einfaches Array, keine paginierte Liste. Die zugehörige Route /listings/additional gibt die kostenlosen Verzeichnisse in derselben Struktur zurück; es gibt keinen Abfrageparameter listingType.

Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

Jede Zeile verknüpft site mit einem maschinenlesbaren syncStatus und einem menschenlesbaren displayStatus. lastUpdate gibt an, wann die Zeile zuletzt geändert wurde, was dabei hilft, eine ins Stocken geratene Einreichung zu erkennen.

2. Status jeder Plattform auslesen

syncStatus ist das Feld, anhand dessen Sie Ihre Verarbeitungslogik verzweigen. displayStatus ist der Text, den Sie einer Person anzeigen, und syncIssue enthält die Begründung der Plattform, sofern eine vorliegt.

syncStatusBedeutungWas zu tun ist
AVAILABLEBereit zur Einreichung, noch nicht gestartet.Nichts. Der Vorgang wird automatisch fortgesetzt.
IN_PROGRESSBei der Plattform eingereicht, eine Antwort steht noch aus.Warten Sie. Prüfen Sie lastUpdate, wenn bereits Wochen vergangen sind.
PENDING_APPROVALDie Plattform hat den Eintrag erhalten und prüft ihn.Warten Sie.
SYNCED oder COMPLETEDVeröffentlicht. listingUrl ist ausgefüllt.Erfassen Sie den Link (Schritt 3).
REQUIRING_ACTIONBlockiert, bis Sie tätig werden. actionRequired ist true.Lesen Sie displayStatus und anschließend Fehler bei Einträgen finden und beheben.
FAILEDDie Plattform hat den Eintrag abgelehnt oder konnte ihn nicht verarbeiten.Lesen Sie syncIssue, korrigieren Sie den Standort und fragen Sie den Status erneut ab.
CANNOT_SUBMITDiese Plattform kann diesen Standort grundsätzlich nicht aufnehmen.In der Regel handelt es sich um ein Land oder eine Kategorie, die von der Plattform nicht unterstützt wird.

Google Maps und Facebook bleiben bei REQUIRING_ACTION, bis das Konto der jeweiligen Plattform verbunden ist: ein Google Business Profile für Google Maps und eine Facebook-Seite für Facebook. Das ist bei einem neuen Standort zu erwarten und kein Fehler.

Apple Maps erfordert keine Verbindung. Wenn der Inhaber kein verifiziertes Apple Business-Organisationskonto verbunden hat, reicht ListingsAPI den Standort über sein eigenes Apple Business Connect-Konto ein, und Apple prüft die Einreichung vor der Veröffentlichung. Siehe Apple Business Connect verbinden.

listingUrl ist nur in Zeilen mit veröffentlichten Einträgen gesetzt. Filtern Sie nach SYNCED (und COMPLETED) und speichern Sie die URL zusammen mit dem Namen der Website, damit Sie eine Liste mit Links zum Anzeigen der veröffentlichten Einträge darstellen oder die URL Ihrem eigenen Datensatz zuordnen können.

Live links
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

Eine Zeile mit SYNCED, bei der listingUrl den Wert null hat, kommt durchaus vor: Manche Verzeichnisse stellen keine öffentliche Seiten-URL bereit. Betrachten Sie den Status als maßgeblich und den Link als optional.

4. Eine Übersicht zur Abdeckung erstellen

Wenn Sie die Zeilen nach syncStatus zählen, erhalten Sie für jeden Standort eine kompakte Statusübersicht: auf wie vielen Plattformen die Einträge veröffentlicht sind, bei wie vielen sie noch in Bearbeitung sind und bei wie vielen sie blockiert sind. Diese Kennzahl eignet sich für ein Dashboard.

Coverage
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

Führen Sie dies für viele Standorte aus, indem Sie GET /locations seitenweise abrufen und den Premium-Endpunkt einmal pro Standort aufrufen. Jeder Aufruf zählt gegen Ihr Ratenlimit. Lassen Sie daher zwischen den Aufrufen eine Pause und beachten Sie Retry-After bei 429. Fehler bei Einträgen finden und beheben zeigt diese Schleife als Durchlauf über alle Standorte innerhalb eines Kontos.

5. Sprachassistenten prüfen

Sprachassistenten (Google Assistant, Alexa, Siri, Cortana, Bixby) haben einen eigenen Endpunkt, GET /locations/{locationId}/voice-assistants, mit einer kleineren Auswahl an Statuswerten. Google Assistant hängt von der Google-Verbindung ab, daher besteht bei einem Standort ohne diese Verbindung auch hier Handlungsbedarf. Die Ergebnisse für Siri stammen aus dem Apple Maps-Eintrag des Standorts.

Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}
syncStatusBedeutung
NOT_SUBMITTEDNoch nicht an den Assistenten gesendet.
IN_PROGRESSÜbermittlung läuft.
REQUIRING_ACTIONWartet auf eine Aktion von Ihnen; lesen Sie syncIssue.
LIVEVeröffentlicht.

Für einen Sprachassistenten gibt es keinen Live-Link; LIVE ist der Endzustand.

6. Webhook-Ereignisse statt Polling empfangen

Wenn Sie unter /dashboard/webhooks eine Webhook-URL konfiguriert haben, wird das Ereignis listing.submission jedes Mal ausgelöst, wenn eine Übermittlung an eine Plattform für einen Standort einen Endzustand erreicht. Es enthält status (success, incomplete oder canceled), die Website und im Erfolgsfall live_link, also dieselbe URL, die Sie in Schritt 3 erfasst haben.

Route listing.submission
import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

Antworten Sie innerhalb von 5 Sekunden mit 200 und führen Sie die Verarbeitung anschließend durch; es gibt keine Wiederholungsversuche. Das Grundgerüst für den Empfänger und die Signaturprüfung finden Sie unter Mit Webhooks auf Ereignisse reagieren.

Nächste Schritte