/api/v4/locations/{locationId}/listings/premiumOttieni le schede premium di una sede
Restituisce lo stato di sincronizzazione di ogni directory delle piattaforme di pubblicazione nel piano di una sede.
Parametri
Percorso
| Nome | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| locationId | string | obbligatorio | Location to read. Accepts a base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
Risposte
200Array of listings with per-directory sync status.
{ "data": { "listingsForLocation": [ { "id": "TGlzdGluZzoxMDQ0Njg3MjM=", "databaseId": "104468723", "site": { "id": "U2l0ZTox", "databaseId": "1", "name": "Google Maps", "url": "maps.google.com", "syScore": "100" }, "syncStatus": "REQUIRING_ACTION", "displayStatus": "Connect your account to sync the listing", "actionRequired": true, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:28Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MTQ=", "databaseId": "104468714", "site": { "id": "U2l0ZToxODA=", "databaseId": "180", "name": "Bing", "url": "www.bing.com", "syScore": "97" }, "syncStatus": "IN_PROGRESS", "displayStatus": "Information submitted to partner; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:35Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3Mjc=", "databaseId": "104468727", "site": { "id": "U2l0ZTozODc=", "databaseId": "387", "name": "BeLocalFocussed", "url": "belocalfocussed.com", "syScore": "80" }, "syncStatus": "SYNCED", "displayStatus": "Synced", "actionRequired": false, "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e", "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:30Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MDk=", "databaseId": "104468709", "site": { "id": "U2l0ZTozMDE=", "databaseId": "301", "name": "Local Mint", "url": "localmint.com", "syScore": "69" }, "syncStatus": "FAILED", "displayStatus": "Partner experiencing issues; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:34:03Z", "indexStatus": false, "syncIssue": "Publisher requires website URL", "verified": false } ] }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
Restituisce lo stato di sincronizzazione di ogni directory delle piattaforme di pubblicazione inclusa nel piano di una sede. Ogni record associa un site (metadati della directory) a un syncStatus e a un displayStatus leggibile da una persona. L'esempio qui sopra è una versione ridotta della risposta effettiva per Jenny Home (che restituisce oltre 30 directory), per mostrare un record per ciascuno degli stati comuni.
Il livello della scheda fa parte del percorso: /listings/premium restituisce le directory premium del piano (mostrate qui) e /listings/additional restituisce le schede aggiuntive/gratuite. Non esiste un parametro di query listingType; un valore inviato in quel parametro viene ignorato.
Caso d'uso: una dashboard sullo stato delle schede
Recupera le schede premium di una sede e raggruppale per syncStatus per mostrare a colpo d'occhio la copertura e quante directory sono attive, in elaborazione o bloccate. Mostra listingUrl per le righe SYNCED, in modo che gli utenti possano fare clic per aprire la scheda pubblicata, e leggi displayStatus/syncIssue per tutto ciò che non è sincronizzato (e.g. Publisher requires website URL).
Caso d'uso: mostra gli impedimenti che richiedono di collegare l'account
Filtra per actionRequired: true per creare l'elenco delle attività del proprietario. Nei dati effettivi, Google Maps, Facebook e Waze vengono restituiti come REQUIRING_ACTION con displayStatus: "Connect your account to sync the listing"; richiedono una connessione OAuth prima di potersi sincronizzare. Indirizza il proprietario al flusso di connessione corrispondente, quindi interroga nuovamente questo endpoint per seguire l'avanzamento dello stato.
Valori di syncStatus: AVAILABLE (pronto per la sincronizzazione, non avviata), IN_PROGRESS (inviato al partner, in attesa di risposta), PENDING_APPROVAL (in attesa dell'approvazione del partner), SYNCED / COMPLETED (pubblicato; listingUrl valorizzato), REQUIRING_ACTION (è necessario un intervento del proprietario, vedi displayStatus), FAILED (sincronizzazione non riuscita; vedi syncIssue), CANNOT_SUBMIT (invio non possibile).
Questo elenco riguarda una singola sede ed è soggetto al limite di frequenza delle richieste dell'account; in caso di 429, riprova dopo l'intervallo indicato nell'header Retry-After anziché interrogare di nuovo immediatamente l'endpoint.
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/listings/premium' \ -H "Authorization: API $LISTINGSAPI_KEY"