Listings APIListings API
Accedi

Crea il primo Google Business Profile per una sede

Richiedi un nuovo Google Business Profile per una sede con account Google collegato e segui la verifica tramite sede, schede e webhook.

L'abbinamento e il collegamento funzionano solo quando esiste già una scheda Google. Un nuovo punto vendita non ne ha una, quindi chiedi all'API di crearla in un account Google collegato. La creazione è asincrona e Google verifica il profilo secondo le proprie tempistiche, quindi gran parte di questa guida riguarda il monitoraggio dell'esito.

1. Verifica che la sede non abbia una scheda Google

Leggi le schede premium della sede e trova la riga il cui site.name è Google Maps. Una sede senza presenza su Google mostra REQUIRING_ACTION con connectedAccountId pari a null.

Google row
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "site": { "name": "Google Maps", "url": "maps.google.com" },  "syncStatus": "REQUIRING_ACTION",  "displayStatus": "Connect your account to sync the listing",  "listingUrl": null,  "connectedAccountId": null,  "verified": false}

Se la riga è già SYNCED o se connectedAccountId è impostato, la sede ha una scheda Google e questa guida non si applica. Collegala o aggiornala.

2. Scegli una cartella (facoltativo)

Google organizza le schede di un account in cartelle, chiamate anche gruppi di account. Elenca le cartelle dell'account collegato e passane una come folderId se il proprietario vuole inserire il nuovo profilo in un gruppo specifico. Salta questo passaggio per crearlo nella radice dell'account.

Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

Usa folderId senza modificarlo; è la stringa accounts/{id}, non un numero. locationCount può essere null quando Google non lo comunica. L'endpoint è valido solo per le connessioni GoogleAccount.

3. Crea la scheda

Invia il valore id della sede in base64 e l'account, oltre alla cartella se ne hai scelta una. La risposta indica soltanto che la richiesta è stata accettata.

Create listing
curl -X POST https://listingsapi.com/api/v4/locations/create/gmb-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": { "clientMutationId": null, "success": true, "errors": null }  }}

success: true significa che la creazione è stata avviata, non che il profilo sia online. Google esamina ogni nuovo profilo prima di pubblicarlo e questo può richiedere giorni. Quando success è false, errors ne indica il motivo: alla sede mancano campi obbligatori, la sede ha già una scheda Google, è archiviata oppure l'account collegato non è più attivo.

4. Monitora lo stato di verifica della sede

Ogni lettura della sede restituisce googleVerificationStatus con un status e un message. Leggi di nuovo la sede per vedere a che punto è Google nel processo.

Verification status
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "id": "TG9jYXRpb246MTgwMDI4OQ==",  "databaseId": 1800289,  "googleVerificationStatus": { "status": "PENDING_VERIFICATION", "message": null }}
statusSignificatoTerminale
NOT_CONNECTEDNon è ancora associata alcuna scheda Google. Questo è lo stato previsto prima che il passaggio 3 abbia effetto.No
NOT_VERIFIEDLa scheda esiste, la verifica non è iniziata.No
PENDING_VERIFICATIONGoogle sta verificando il profilo.No
UNDER_REVIEWGoogle sta esaminando il profilo.No
VERIFIEDIl profilo è online.Sì
SUSPENDEDGoogle ha sospeso il profilo.Sì
DUPLICATEGoogle lo ha considerato un duplicato di un profilo esistente.Sì
ERROR_WHILE_FETCHINGNon è stato possibile leggere lo stato da Google. Riprova più tardi.Sì

Una lettura al giorno è sufficiente per un processo che richiede giorni. Rispetta Retry-After in caso di 429 se controlli molte sedi contemporaneamente.

5. Monitora la riga di Google nelle schede

La riga delle schede premium del passaggio 1 mostra lo stesso avanzamento dal lato della scheda. Esegui di nuovo la chiamata del passaggio 1 e leggi syncStatus, verified e listingUrl.

syncStatusSignificato
REQUIRING_ACTIONNon è ancora stato creato nulla oppure l'account richiede attenzione. Vedi displayStatus.
IN_PROGRESSInviata a Google, in attesa di risposta.
PENDING_APPROVALIn attesa dell'approvazione di Google.
SYNCEDOnline. listingUrl è valorizzato e connectedAccountId identifica l'account.
FAILEDGoogle ha rifiutato la richiesta. syncIssue ne indica il motivo.

6. Ascolta i webhook di verifica

Se nella dashboard è impostato un URL webhook, due eventi coprono gli stati finali, quindi non devi effettuare il polling. Entrambi includono location_id e hanno sempre data.connected_account_id: null.

EventoSi attiva quandoCampi di data
connection.google_verification_verifiedIl profilo raggiunge VERIFIED.platform: "google"
connection.google_verification_failedIl profilo raggiunge SUSPENDED o DUPLICATE (failure_type: "rejected") o ERROR_WHILE_FETCHING (failure_type: "transient").platform, failure_type, reason
JSON
{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}

Vale la pena riprovare solo in caso di errori transient. Gli stati in corso non generano alcun evento, quindi il silenzio non è un segnale: mentre una verifica è in corso, leggi googleVerificationStatus come nel passaggio 4.

Passaggi successivi