Schede

Tutti gli endpoint Listings con esempi cURL, Python e Node: stato sync premium, assistenti vocali, rilevamento duplicati per sede/account e soppressione.

Una scheda è la voce di una sede nella directory di una piattaforma di pubblicazione. La creazione di una sede mette in coda una scheda per ogni piattaforma di pubblicazione inclusa nel tuo piano, e gli endpoint per le schede consentono di leggere lo stato di ciascuna, elencare i duplicati rilevati e confermarli o scartarli. I quattro endpoint GET funzionano con una chiave Read (lettura); i due endpoint POST richiedono una chiave Write (scrittura).

Panoramica degli endpoint

Leggi lo stato delle schede premium

GET /locations/{locationId}/listings/premium

Restituisce un record per ogni piattaforma di pubblicazione premium inclusa nel piano della sede, sotto data.listingsForLocation. È un semplice array, non un elenco paginato. Il percorso parallelo /listings/additional restituisce le directory gratuite nella stessa struttura; non esiste alcun parametro di query listingType e un valore inviato con quel parametro viene ignorato.

Parametri

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "listingsForLocation": [      {        "id": "TGlzdGluZzoxMDQ0Njg3MjM=",        "site": { "databaseId": "1", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3Mjc=",        "site": { "databaseId": "387", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3MDk=",        "site": { "databaseId": "301", "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "listingUrl": null,        "syncIssue": "Publisher requires website URL",        "lastUpdate": "2026-07-06T18:34:03Z"      }    ]  }}

Gestisci i diversi casi in base a syncStatus. Mostra displayStatus a una persona, leggi syncIssue per conoscere la motivazione fornita dalla piattaforma di pubblicazione e usa lastUpdate per individuare un invio che si è bloccato. listingUrl è impostato solo nelle righe relative alle schede pubblicate.

Google Maps, Facebook e Waze rimangono nello stato REQUIRING_ACTION con displayStatus: "Connect your account to sync the listing" finché non viene collegato l'account corrispondente. È il comportamento previsto per una nuova sede.

Leggi lo stato degli assistenti vocali

GET /locations/{locationId}/voice-assistants

Restituisce un record per ogni assistente vocale sotto data.voiceAssistantsForLocation: Google Assistant, Amazon Alexa, Apple Siri, Microsoft Cortana e Samsung Bixby. È un semplice array con un insieme di stati più ristretto rispetto all'endpoint premium.

Parametri

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "voiceAssistantsForLocation": [      {        "databaseId": "104468723",        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "connectedAccountId": null,        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "databaseId": "104468711",        "voiceIdentifier": "SIRI",        "name": "Siri",        "connectedAccountId": null,        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}

Segnala ogni riga in cui actionRequired è true oppure syncIssue è impostato. errors contiene le stringhe di errore della piattaforma di pubblicazione, mentre connectedAccountId identifica l'account collegato tramite cui avviene la sincronizzazione, quando applicabile. I risultati di Google Assistant provengono dal collegamento a Google Business Profile, quindi l'assenza di un collegamento a Google è il motivo più comune per cui è necessario intervenire. I risultati di Siri provengono dalla scheda della sede su Apple Maps.

Riepiloga i duplicati di tutto l'account

GET /locations/listings/duplicates

Restituisce tutti i duplicati rilevati accessibili alla chiave, per tutte le sedi e le piattaforme di pubblicazione, in data.duplicateListingsRollup. La paginazione è basata su offset: page e perPage in ingresso, records[] più pageInfo.totalRecords, pageInfo.totalPages e pageInfo.hasNextPage in uscita. I filtri sono parametri di query semplici, non JSON. Se non fornisci alcun parametro, status assume il valore predefinito POTENTIAL e tag il valore all, quindi una chiamata senza parametri restituisce i duplicati aperti dell'account.

Parametri

I wrapper Python e Node espongono solo tag e page. Per filtrare per status o siteId, o per impostare perPage, chiama direttamente la route come mostrato in Gestire le schede duplicate.

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsRollup": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "totalPages": 34,        "totalRecords": 1673      },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "nameValid": false,          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

Il riepilogo indica dove si trovano i duplicati: ogni record specifica locationId e siteName. duplicateProcessingState è lo stesso stato del ciclo di vita che l'endpoint per singola sede riporta come status. Scorri le pagine una alla volta finché hasNextPage non è false; un ciclo senza pause è il modo più rapido per ottenere un 429.

Elenca i duplicati di una singola sede

GET /locations/{locationId}/listings/duplicates

Restituisce tutti i duplicati rilevati per una singola sede in data.duplicateListingsForLocation, raggruppati per sito della piattaforma di pubblicazione. È un semplice array. Ogni gruppo è un sito (name, url) con un array listings e ogni voce contiene il listingItemId accettato da entrambi gli endpoint di contrassegno. Un array vuoto indica che non è stato rilevato nulla.

Parametri

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/duplicates \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

Apri liveLink per esaminare la voce, poi conserva listingItemId. Nel Node SDK, il campo d.id ottenuto dall'appiattimento è il valore da passare. status usa gli stessi quattro valori del riepilogo dell'account riportato sopra.

Conferma gli elementi delle schede come duplicati

POST /locations/listings/mark-as-duplicate

Contrassegna gli elementi delle schede come duplicati confermati, in modo che possano essere soppressi presso la piattaforma di pubblicazione. Invia i valori listingItemId in input e raggruppa tutti gli elementi confermati di una sede in un'unica chiamata anziché effettuare una chiamata per ogni elemento. Questa è un'operazione di scrittura e richiede una chiave Write (scrittura).

Parametri

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true indica che gli elementi sono stati accettati e passano a PROCESSING. Un 200 con success: false, oppure un 400, è accompagnato da un array errors le cui voci contengono code, message e path; la causa più comune è un id sconosciuto o non valido. Il Python SDK restituisce il payload; il Node SDK, invece, genera un'eccezione ValidationError, quindi una promise risolta indica che l'operazione è riuscita.

Escludi gli elementi delle schede dai duplicati

POST /locations/listings/mark-as-not-duplicate

Esclude i potenziali duplicati in quanto falsi positivi. Il rilevamento è prudente e segnala anche un'altra sede dello stesso franchising, un secondo profilo legittimo o una sede rinominata. Una volta esclusi, gli elementi non compaiono più in nessuno dei due endpoint dei duplicati. Accetta lo stesso body dell'endpoint precedente e consente anche di annullare il contrassegno di un elemento segnalato per errore.

Parametri

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

{  "data": {    "markAsNotDuplicate": {      "success": true,      "errors": null    }  }}

La risposta è data.markAsNotDuplicate con gli stessi campi success e errors della chiamata per contrassegnare un elemento come duplicato. Un elemento escluso viene registrato come non duplicato confermato e non ricompare al successivo ciclo di rilevamento.

Errori che potresti riscontrare

Tutti i codici sono elencati nella documentazione di riferimento degli errori.

Passaggi successivi

• Controlla lo stato delle schede e i link attivi: trasforma gli endpoint premium e voice in una dashboard della copertura.
• Trova e correggi gli errori delle schede: esamina e gestisci le righe REQUIRING_ACTION e FAILED.
• Gestisci le schede duplicate: il ciclo di verifica tramite i quattro endpoint dei duplicati, incluso il monitoraggio dello stato.
• Collega Google e importa le sedi: collega il Google Business Profile utilizzato da Google Maps e Google Assistant.
• Collega Apple Business Connect: pubblica su Apple Maps tramite l'account Apple Business verificato del proprietario.
• Pagina principale della risorsa: Schede. Documentazione di riferimento degli SDK: Schede in Python, Schede in Node.