Listings APIListings API
Accedi

Controlla lo stato delle schede e ottieni i link attivi

Sincronizzazione e URL attivi delle schede per sede e piattaforma di pubblicazione, copertura e assistenti vocali. Ricevi webhook anziché polling.

Una volta creata una sede, viene inviata automaticamente una scheda per ogni piattaforma di pubblicazione inclusa nel tuo piano. Questa guida mostra come leggere lo stato di ciascuna scheda, recuperare gli URL delle schede pubblicate e interrompere il polling una volta configurati i webhook.

1. Recupera le schede premium di una sede

GET /locations/{locationId}/listings/premium restituisce un record per ogni piattaforma di pubblicazione premium inclusa nel piano. È un semplice array, non un elenco paginato. La route analoga /listings/additional restituisce le directory gratuite con la stessa struttura; non esiste un parametro di query 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"      }    ]  }}

Ogni riga associa un valore site a un valore syncStatus leggibile dalle macchine e a un valore displayStatus leggibile dalle persone. lastUpdate indica quando la riga è stata modificata l'ultima volta, il che è utile per individuare un invio che non avanza più.

2. Leggi lo stato di ogni piattaforma di pubblicazione

syncStatus è il campo su cui basare le condizioni del codice. displayStatus è il testo da mostrare a una persona e syncIssue contiene la motivazione della piattaforma di pubblicazione, quando presente.

syncStatusSignificatoCosa fare
AVAILABLEPronta per l'invio, che non è ancora iniziato.Nulla. Avanza automaticamente.
IN_PROGRESSInviata alla piattaforma di pubblicazione, in attesa di una risposta.Attendi. Controlla lastUpdate se sono trascorse settimane.
PENDING_APPROVALLa piattaforma di pubblicazione l'ha ricevuta e la sta esaminando.Attendi.
SYNCED o COMPLETEDPubblicata. listingUrl è valorizzato.Raccogli il link (passaggio 3).
REQUIRING_ACTIONBloccata in attesa di un tuo intervento. actionRequired è true.Leggi displayStatus, poi consulta Individua e correggi gli errori delle schede.
FAILEDLa piattaforma di pubblicazione l'ha rifiutata o non ha potuto elaborarla.Leggi syncIssue, correggi la sede ed esegui di nuovo il polling.
CANNOT_SUBMITQuesta piattaforma di pubblicazione non può accettare questa sede in alcun caso.Di solito si tratta di un paese o di una categoria non supportati dalla piattaforma di pubblicazione.

Google Maps e Facebook rimangono nello stato REQUIRING_ACTION finché non viene collegato l'account della rispettiva piattaforma di pubblicazione: un Google Business Profile per Google Maps e una Pagina Facebook per Facebook. È una situazione prevista per una nuova sede, non un errore.

Apple Maps non richiede un collegamento. Se il proprietario non ha collegato un account aziendale verificato di Apple Business, ListingsAPI invia la sede tramite il proprio account Apple Business Connect e Apple verifica l'invio prima di pubblicare la scheda. Consulta Collega Apple Business Connect.

listingUrl è valorizzato solo nelle righe delle schede pubblicate. Filtra per SYNCED (e COMPLETED) e conserva l'URL insieme al nome del sito, così puoi visualizzare un elenco con link «vedi la scheda pubblicata» o salvarlo nel tuo record.

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

Può capitare che una riga SYNCED abbia listingUrl impostato su null: alcune directory non espongono l'URL di una pagina pubblica. Considera lo stato come fonte autorevole e il link come facoltativo.

4. Crea un riepilogo della copertura

Contare le righe per syncStatus fornisce un indicatore sintetico dello stato di ogni sede: quante piattaforme di pubblicazione hanno una scheda pubblicata, quante sono ancora in fase di elaborazione e quante sono bloccate. Questo è il numero da mostrare in una 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})'

Esegui questa operazione su più sedi scorrendo le pagine di GET /locations e chiamando l'endpoint premium una volta per sede. Ogni chiamata viene conteggiata ai fini del tuo limite di frequenza, quindi lascia un intervallo tra una chiamata e l'altra e rispetta Retry-After quando ricevi 429. Individua e correggi gli errori delle schede mostra il ciclo come una scansione dell'intero account.

5. Controlla gli assistenti vocali

Gli assistenti vocali (Google Assistant, Alexa, Siri, Cortana, Bixby) hanno un proprio endpoint, GET /locations/{locationId}/voice-assistants, con un insieme di stati più ridotto. Google Assistant dipende dalla connessione a Google, quindi una sede che ne è priva richiede attenzione anche qui. I risultati di Siri provengono dalla scheda della sede su Apple Maps.

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": []      }    ]  }}
syncStatusSignificato
NOT_SUBMITTEDNon ancora inviata all'assistente.
IN_PROGRESSInvio in corso.
REQUIRING_ACTIONBloccata in attesa di un tuo intervento; leggi syncIssue.
LIVEPubblicata.

Non esiste un link pubblico per un assistente vocale; LIVE è lo stato finale.

6. Ricevi eventi webhook invece di effettuare il polling

Se hai configurato un URL webhook in /dashboard/webhooks, l'evento listing.submission viene generato ogni volta che un invio a una piattaforma di pubblicazione per una singola sede raggiunge uno stato terminale. Contiene status (success, incomplete o canceled), il sito e, in caso di successo, live_link, che è lo stesso URL che hai raccolto al passaggio 3.

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"))

Rispondi con 200 entro 5 secondi ed esegui il lavoro in seguito; non sono previsti nuovi tentativi. Per la struttura di base del ricevitore e la verifica della firma, consulta Reagisci agli eventi con i webhook.

Passaggi successivi