Listings APIListings API
Anmelden

Google Business Profile verbinden und Standorte importieren

Google-Verbindungslink erstellen, Google-Einträge des Inhabers Ihren Standorten zuordnen, Zuordnungen bestätigen und Einträge ohne Standort importieren.

Ein verbundenes Google-Konto ermöglicht die Veröffentlichung und Berichterstellung für einen Standort auf Google. Solange kein Konto verbunden ist, bleibt die Zeile für Google Maps in den Premium-Einträgen eines Standorts auf REQUIRING_ACTION, Google-Bewertungen werden nicht abgerufen, Beiträge können nicht auf GOOGLE veröffentlicht werden und Google-Analysedaten werden als null zurückgegeben. Durch das Verbinden des Kontos werden alle vier Einschränkungen behoben.

Der Ablauf für die Massenverknüpfung (Schritte 1 bis 6) verbindet einmalig ein gesamtes Google-Konto und gleicht alle Einträge, die diesem Konto gehören, mit Ihren Standorten ab. Der Ablauf für einzelne Standorte (Schritt 7) verbindet jeweils einen Standort: Der Link ist an diesen Standort gebunden, daher folgt kein Abgleich.

Der Link ist auf das Konto beschränkt, dem der API-Schlüssel gehört, daher enthält der Anfrage-Body nur Ihre beiden Weiterleitungs-URLs. Leiten Sie den Inhaber an den zurückgegebenen Wert url weiter; Google leitet ihn nach Abschluss an successUrl oder errorUrl zurück.

Connect link
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-google \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "successUrl": "https://app.example.com/connect/google/success",    "errorUrl": "https://app.example.com/connect/google/error"  }}'
JSON
{  "data": {    "bulkConnectLinkForGoogle": {      "success": true,      "url": "https://connect.example.com/oauth?token=8f3c1d92-...",      "errors": null    }  }}

Der obige Wert url ist ein Platzhalter. Leiten Sie den Inhaber an den Wert url weiter, der in Ihrer eigenen Antwort zurückgegeben wird.

Der Link ist 24 Stunden gültig. Prüfen Sie, ob url nicht null ist, anstatt sich allein auf success zu verlassen. Wenn die Zugangsdaten des Inhabers später ablaufen, erstellen Sie auf dieselbe Weise einen neuen Link: Die bestehende Verbindung wird aktualisiert und nicht dupliziert.

2. Verbundene Konten nach der Rückkehr von OAuth auflisten

Wenn der Inhaber auf Ihrer URL successUrl ankommt, listen Sie die Google-Konten auf. Dies ist eine offsetbasierte Ergebnisseite: records[] plus pageInfo.totalRecords, mit Seitennavigation über page und perPage.

List accounts
curl "https://listingsapi.com/api/v4/connected-accounts?publisher=GoogleAccount&page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectedAccountsInfo": {      "pageInfo": { "hasNextPage": false, "totalRecords": 1 },      "records": [        {          "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",          "email": "owner@brightsmile-dental.com",          "status": "CONNECTED",          "requestMatchesStatus": "MATCH_COMPLETED",          "connectedLocationsCount": 0        }      ]    }  }}

Wählen Sie den Datensatz, dessen email dem Inhaber entspricht, der gerade zugestimmt hat, und speichern Sie dessen connectedAccountId. Jeder spätere Aufruf verwendet diese UUID.

statusBedeutung
CONNECTEDDie Zugangsdaten sind gültig. Der Abgleich kann ausgelöst werden.
MATCH_IN_PROGRESSEin Abgleich befindet sich in der Warteschlange oder wird ausgeführt.
CONNECTIVITY_ISSUEDie erteilte Berechtigung ist abgelaufen. connectivityIssue gibt den Grund an; stellen Sie den Verbindungslink erneut aus.

Der optionale Abfragefilter status verwendet andere Bezeichnungen (Connected, NotConnected, ConnectionIssue); wenn Sie den Wert status eines Datensatzes wieder als Filterwert übergeben, wird 400 zurückgegeben.

3. Abgleich auslösen

Der Abgleich ruft jedes Profil ab, auf das das Konto zugreifen kann, und ordnet es jeweils einem Ihrer Standorte zu. Dabei werden nur Vorschläge erstellt; es wird noch nichts verknüpft.

Trigger matches
curl -X POST https://listingsapi.com/api/v4/connected-accounts/trigger-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "connectedAccountIds": ["4f712c17-4f95-42dd-90f4-97171a2e67b5"] } }'

Die Antwort lautet data.connectedAccountsTriggerMatches mit success und failedIds. success: true bedeutet, dass der Auftrag in die Warteschlange aufgenommen wurde; jedes Konto, das nicht in die Warteschlange aufgenommen werden konnte, wird in failedIds aufgeführt.

4. Wiederholt abfragen, bis MATCH_COMPLETED erreicht ist

Fragen Sie die Kontodetails alle 15 Sekunden in einer begrenzten Schleife ab. Dieses Intervall hält auch im Launch-Tarif die Grenze von 10 Anfragen pro Minute ein.

Poll details
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/details \-H "Authorization: API $LISTINGSAPI_KEY"

Der Datensatz wird unter data.connectedAccountDetails.details zurückgegeben und enthält dieselben Felder wie ein Datensatz aus der Liste. requestMatchesStatus hat während der Ausführung des Auftrags den Wert MATCH_IN_PROGRESS und den Wert MATCH_COMPLETED, sobald die Vorschläge bereitstehen. Completed bedeutet, dass der Abgleich abgeschlossen ist, nicht dass etwas verknüpft wurde: connectedLocationsCount bleibt auf 0, bis Sie bestätigen.

5. Vorschläge prüfen und bestätigen

Jeder Vorschlag ordnet einen Ihrer Standorte (locationInfo, dessen databaseId den Wert locationId hat) einem Google-Eintrag (suggestedLocationInfo) zu. Zeigen Sie beide Seiten einer zuständigen Person an oder akzeptieren Sie den Vorschlag automatisch, wenn Name und Stadt übereinstimmen.

Suggestions
curl "https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/connection-suggestions?page=1&perPage=20" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "connectionSuggestionsForAccount": {      "pageInfo": { "hasNextPage": false, "totalRecords": 2 },      "records": [        {          "accountType": "GMB",          "matchedDataDatabaseId": "0d5e306f-0da0-46e3-929f-fd3c67ccd8cc",          "locationId": "73415",          "locationInfo": { "name": "My Business", "city": "Lincoln", "stateIso": "NE" },          "suggestedLocationInfo": { "locationInfo": { "name": "My Business", "city": "Lincoln" } }        }      ]    }  }}

Ein Vorschlag hat keine id. Zur Bestätigung erstellen Sie eine ID für den Zuordnungsdatensatz: die Base64-Kodierung von <MatchRecordType>:<matchedDataDatabaseId>, wobei der Typ aus accountType gewählt wird. Für Google (GMB) ist der Typ GmbLocationMatchedData, sodass der obige Datensatz als R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M= kodiert wird. Facebook (FB) verwendet FbLocationMatchedData und Apple (APPLE) verwendet AppleLocationMatchedData.

Confirm matches
# base64 of GmbLocationMatchedData:0d5e306f-0da0-46e3-929f-fd3c67ccd8cccurl -X POST https://listingsapi.com/api/v4/connected-accounts/confirm-matches \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "input": { "matchRecordIds": ["R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M="] } }'

Die Antwort lautet data.confirmConnectMatches mit success und failedIds. failedIds enthält die dekodierten matchedDataDatabaseId-Werte, die nicht bestätigt werden konnten, etwa für einen bereits verwendeten Datensatz oder einen seit dem Abgleich archivierten Standort. Bei einer ID, die mit dem falschen Typ erstellt wurde, wird kein 400 zurückgegeben: Der Aufruf gibt 200 mit success: false und ohne failedIds zurück, prüfen Sie daher jedes Mal success. Nicht gesendete Vorschläge bleiben unverändert.

6. Einträge importieren, die noch keinem Standort zugeordnet sind

Der Abgleich ordnet Einträge nur Standorten zu, die Sie bereits haben. Um die übrigen zu importieren, listen Sie alles auf, was das Konto sehen kann, und erstellen Sie dann aus jedem gewünschten Eintrag einen Standort.

Account listings
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connected-account-listings \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5", "perPage": 50 }'
JSON
{  "data": {    "connectedAccountListings": {      "pageInfo": { "hasNextPage": false, "totalRecords": 60 },      "records": [        {          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "locationName": "Trial",          "address": "123 William St, NY 10038, Manhattan, US",          "liveLink": null        }      ]    }  }}

Übergeben Sie locationInfo mit einem Suchbegriff, um die Ergebnisse für ein großes Konto nach Name, Adresse, Telefonnummer, Postleitzahl oder Filialcode einzugrenzen. id in jedem Datensatz ist der Wert für connectedAccountListingId, den die nächsten beiden Aufrufe entgegennehmen. Keines der beiden SDKs bietet bisher eine Methode für create-location-from-listing, daher rufen die Python- und Node-Beispiele REST direkt mit demselben Header auf.

Create from listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/create-location-from-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'
JSON
{  "data": {    "createLocationFromConnectedAccountListing": { "success": true, "locationId": 88277, "errors": null }  }}

Der Standort wird aus den Google-Daten (Name, Adresse, Öffnungszeiten, Kategorien, Telefonnummer, Attribute) erstellt und sofort mit dem Eintrag verknüpft. Der Google-Eintrag bleibt bei IN_PROGRESS, bis Ihre erste Standortaktualisierung dort veröffentlicht wird. locationId ist der reine databaseId. Bei einem Fehler ist success auf false gesetzt, und errors enthält einen Code wie SY81067 (die Eintrags-ID konnte nicht aufgelöst werden). Das Feld heißt connectedAccountListingId; listingId wird vom Schema abgelehnt.

Wenn der Eintrag zu einem Standort gehört, den Sie bereits haben, verknüpfen Sie ihn, statt ein Duplikat zu erstellen.

Link a listing
curl -X POST https://listingsapi.com/api/v4/connected-accounts/connect-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "connectedAccountListingId": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA=="  }}'

Eine fehlgeschlagene Verknüpfung gibt success: false mit message zurück, beispielsweise Listing record not found, oder einen Hinweis, dass der Eintrag bereits mit einem anderen Standort verbunden ist.

7. Stattdessen einen einzelnen Standort verbinden

Wenn Sie bereits wissen, welchen Standort der Inhaber verbindet, überspringen Sie den Abgleich und erstellen Sie einen Link, der diesem Standort zugeordnet ist. Bei Erfolg wird der Inhaber zu successUrl zurückgeleitet, und die Zugangsdaten werden ausschließlich diesem Standort zugeordnet.

Single-location link
curl -X POST https://listingsapi.com/api/v4/locations/oauth_connect_url \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "site": "GOOGLE",    "successUrl": "https://app.example.com/locations/1800289/connected",    "errorUrl": "https://app.example.com/locations/1800289/connect-failed"  }}'

Die Antwort ist data.createConnectUrl mit success, url und errors. Der Link kann nur einmal verwendet werden, erstellen Sie daher für jeden Versuch einen neuen. Bei einer relativen oder nicht parsebaren Weiterleitungs-URL wird success: true mit null url zurückgegeben, prüfen Sie daher url. Bei einem Schlüssel, der nicht auf diesen Standort zugreifen darf, wird 403 mit SY90003 zurückgegeben.

8. Was als Nächstes passiert

Sobald ein Eintrag verknüpft ist, wechselt die Google Maps-Zeile in den Premium-Einträgen des Standorts von REQUIRING_ACTION über IN_PROGRESS zu SYNCED mit listingUrl. Google wird automatisch als Bewertungsquelle hinzugefügt, sodass Bewertungen in der Interaktionsliste eingehen und Änderungen, die Sie am Standort vornehmen, an das Profil übertragen werden.

Wenn im Dashboard eine Webhook-URL hinterlegt ist, müssen Sie keine regelmäßigen Abfragen durchführen. Jede Nutzlast enthält location_id und data.connected_account_id.

EreignisWird ausgelöst, wennErforderliche Aktion
connection.location_connectedEin Eintrag wird mit einem Standort verknüpft; data.platform ist google.Kennzeichnen Sie den Standort in Ihrer Benutzeroberfläche als verbunden.
connection.reauth_requiredDie Zugangsdaten des Kontos wurden ungültig. Bis zur erneuten Autorisierung wird nichts synchronisiert.Erstellen Sie einen neuen Link (Schritt 1) und bitten Sie den Inhaber, sich erneut anzumelden.
connection.listing_inaccessibleDie Zugangsdaten sind gültig, aber der Zugriff auf diesen einzelnen Eintrag wurde entzogen.Bitten Sie den Inhaber, den Zugriff bei Google wiederherzustellen, oder verknüpfen Sie einen anderen Eintrag.

Nächste Schritte