Listings APIListings API
Accedi

Collega Google Business Profile e importa le tue sedi

Crea un link per collegare Google, associa le schede Google del proprietario alle tue sedi, conferma le associazioni e importa quelle ancora senza sede.

Un account Google collegato consente la pubblicazione e la generazione di report per una sede su Google. Finché non ne viene collegato uno, la riga Google Maps nelle schede premium di una sede rimane REQUIRING_ACTION, le recensioni Google non vengono importate, i post non possono essere pubblicati su GOOGLE e i dati di analisi di Google vengono restituiti come null. Collegare l'account risolve tutti e quattro i problemi.

La procedura in blocco (passaggi da 1 a 6) collega un intero account Google una sola volta e abbina ogni scheda di cui è proprietario alle tue sedi. La procedura per una singola sede (passaggio 7) collega una sede alla volta: il link è associato a quella sede, quindi non segue alcun passaggio di abbinamento.

Il link è limitato all'account a cui appartiene la chiave API, quindi il corpo della richiesta contiene soltanto i tuoi due URL di reindirizzamento. Indirizza il proprietario a url restituito nella risposta; Google lo reindirizza a successUrl o errorUrl al termine della procedura.

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

Il valore url qui sopra è un segnaposto. Indirizza il proprietario a url restituito nella risposta alla tua richiesta.

Il link è valido per 24 ore. Verifica che url non sia null anziché affidarti soltanto a success. Se in seguito le credenziali del proprietario scadono, crea un nuovo link nello stesso modo: il collegamento esistente viene aggiornato, non duplicato.

2. Elenca gli account collegati dopo il ritorno da OAuth

Quando il proprietario arriva su successUrl, elenca gli account Google. Questa pagina usa la paginazione per offset: records[] più pageInfo.totalRecords, con le pagine gestite tramite page e 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        }      ]    }  }}

Scegli il record il cui email corrisponde al proprietario che ha appena dato il consenso e conserva il suo connectedAccountId. Ogni chiamata successiva richiede questo UUID.

statusSignificato
CONNECTEDLe credenziali sono valide. Puoi avviare l'abbinamento.
MATCH_IN_PROGRESSUn'operazione di abbinamento è in coda o in esecuzione.
CONNECTIVITY_ISSUEL'autorizzazione è scaduta. connectivityIssue ne indica il motivo; genera nuovamente il link di collegamento.

Il filtro di query facoltativo status usa termini diversi (Connected, NotConnected, ConnectionIssue); passare come filtro il valore status del record stesso restituisce 400.

3. Avvia l'abbinamento

L'abbinamento recupera tutti i profili a cui l'account può accedere e associa ciascuno a una delle tue sedi. Produce soltanto suggerimenti; non viene ancora collegato nulla.

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

La risposta è data.connectedAccountsTriggerMatches con success e failedIds. success: true indica che l'operazione è stata messa in coda; tutti gli account che non è stato possibile mettere in coda sono elencati in failedIds.

4. Esegui il polling fino a MATCH_COMPLETED

Interroga i dettagli dell'account ogni 15 secondi con un ciclo limitato. Questo intervallo mantiene anche il piano Launch entro il suo limite di 10 richieste al minuto.

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

Il record viene restituito in data.connectedAccountDetails.details e ha gli stessi campi di un record dell'elenco. requestMatchesStatus è MATCH_IN_PROGRESS durante l'esecuzione dell'operazione e MATCH_COMPLETED quando i suggerimenti sono pronti. Completed indica che il sistema di abbinamento ha terminato, non che sia stato collegato qualcosa: connectedLocationsCount rimane 0 finché non confermi.

5. Esamina e conferma i suggerimenti

Ogni suggerimento abbina una delle tue sedi (locationInfo, con locationId come valore di databaseId) a una scheda Google (suggestedLocationInfo). Mostra entrambi gli elementi a un operatore oppure accetta automaticamente quando nome e città coincidono.

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

Un suggerimento non ha un id. Per confermarlo, costruisci un identificativo del record di abbinamento: la codifica base64 di <MatchRecordType>:<matchedDataDatabaseId>, con il tipo scelto da accountType. Per Google (GMB) il tipo è GmbLocationMatchedData, quindi il record qui sopra viene codificato come R21iTG9jYXRpb25NYXRjaGVkRGF0YTowZDVlMzA2Zi0wZGEwLTQ2ZTMtOTI5Zi1mZDNjNjdjY2Q4Y2M=. Facebook (FB) usa FbLocationMatchedData e Apple (APPLE) usa 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="] } }'

La risposta è data.confirmConnectMatches con success e failedIds. failedIds contiene i valori matchedDataDatabaseId decodificati che non è stato possibile confermare, ad esempio un record già utilizzato o una sede archiviata dopo l'abbinamento. Un identificativo costruito con il tipo sbagliato non restituisce 400: la chiamata restituisce 200 con success: false e senza failedIds, quindi controlla success ogni volta. I suggerimenti non inviati rimangono invariati.

6. Importa le schede che non hanno ancora una sede

L'abbinamento associa le schede solo alle sedi che hai già. Per importare le altre, elenca tutte le schede visibili all'account, quindi crea una sede da ogni scheda che vuoi importare.

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

Passa locationInfo con un termine di ricerca per filtrare le schede di un account di grandi dimensioni per nome, indirizzo, telefono, codice postale o codice negozio. Il valore id di ogni record è il valore connectedAccountListingId accettato dalle due chiamate successive. Nessuno dei due SDK offre ancora un metodo per create-location-from-listing, quindi gli esempi Python e Node chiamano direttamente REST con la stessa intestazione.

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

La sede viene creata a partire dai dati di Google (nome, indirizzo, orari, categorie, telefono, attributi) e collegata immediatamente alla scheda. La scheda Google rimane nello stato IN_PROGRESS finché il primo aggiornamento della sede non viene pubblicato sulla scheda. locationId è semplicemente databaseId. In caso di errore, success è false e errors contiene un codice come SY81067 (non è stata trovata una scheda corrispondente all'id). Il campo è connectedAccountListingId; listingId viene rifiutato dallo schema.

Se la scheda appartiene a una sede che hai già, collegala invece di creare un duplicato.

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

Se il collegamento non riesce, viene restituito success: false con un message, ad esempio Listing record not found, oppure una nota che indica che la scheda è già collegata a un'altra sede.

7. Collega invece una singola sede

Quando sai già quale sede sta collegando il proprietario, salta l'abbinamento e crea un link associato a quella sede. Se l'operazione riesce, il proprietario torna al tuo successUrl e le credenziali vengono associate solo a quella sede.

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

La risposta è data.createConnectUrl con success, url e errors. Il link è monouso, quindi creane uno nuovo per ogni tentativo. Se l'URL di reindirizzamento è relativo o non può essere interpretato, viene restituito success: true con un null url, quindi controlla url. Una chiave che non è autorizzata a operare su questa sede riceve 403 con SY90003.

8. Cosa succede dopo

Una volta collegata una scheda, la riga Google Maps nelle schede premium della sede passa da REQUIRING_ACTION a IN_PROGRESS e infine a SYNCED con un listingUrl. Google viene aggiunto automaticamente come fonte di recensioni, quindi le recensioni iniziano ad arrivare nell'elenco delle interazioni e gli aggiornamenti che apporti alla sede vengono trasmessi al profilo.

Se imposti un URL webhook nella dashboard, non devi eseguire il polling. Ogni payload contiene location_id e data.connected_account_id.

EventoSi attiva quandoCosa fare
connection.location_connectedUna scheda viene collegata a una sede; data.platform è google.Indica nell'interfaccia che la sede è collegata.
connection.reauth_requiredLe credenziali dell'account sono state invalidate. Non viene sincronizzato nulla finché non viene concessa nuovamente l'autorizzazione.Crea un nuovo link (passaggio 1) e chiedi al proprietario di accedere di nuovo.
connection.listing_inaccessibleLe credenziali sono valide, ma l'accesso a quella singola scheda è stato revocato.Chiedi al proprietario di ripristinare l'accesso su Google oppure collega una scheda diversa.

Passaggi successivi