Analisi

Tutti gli endpoint di analisi del profilo con esempi cURL, Python e Node: metriche Google e Facebook giornaliere e viste Bing settimanali per sede.

Le analisi del profilo indicano con quale frequenza una sede è stata visualizzata e ha ricevuto interazioni su ciascuna piattaforma di pubblicazione: impressioni, visualizzazioni di pagina, richieste di indicazioni stradali, chiamate e clic sul sito web. Ci sono tre endpoint, uno per piattaforma di pubblicazione, e tutti e tre eseguono operazioni di lettura, quindi è sufficiente una chiave Read (lettura). Ogni metrica è una serie temporale di punti { startTime, value }; l'API non restituisce totali scalari, quindi le somme che mostri sono quelle che calcoli tu.

Panoramica degli endpoint

Tutti e tre condividono gli stessi parametri. fromDate e toDate sono di tipo YYYY-MM-DD, entrambi facoltativi; se li ometti, viene usato l'intervallo recente predefinito della piattaforma di pubblicazione. Il percorso accetta l'id Relay in base64 oppure il semplice numero. Se il valore non corrisponde a nessuno dei due formati, l'endpoint restituisce 200 con l'oggetto insights impostato su null e un array errors, una risposta che sembra indicare un profilo non collegato, quindi controlla prima errors.

Leggi le metriche di Google per un intervallo di date

GET /locations/{locationId}/google-analytics restituisce data.googleInsights con una serie giornaliera per ogni metrica. total rappresenta le impressioni del profilo, ovvero search più maps; non include le metriche relative alle azioni. Usalo per un report sulla visibilità prima e dopo una modifica ai dati.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "googleInsights": {      "total": [        { "startTime": "2026-08-01T00:00:00+00:00", "value": 412 },        { "startTime": "2026-08-02T00:00:00+00:00", "value": 388 }      ],      "search": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 300 }],      "maps": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 112 }],      "directionsAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 24 }],      "phoneAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 8 }],      "websiteAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 41 }],      "businessBookings": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodOrders": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodMenuClicks": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }]    }  }}

Il campo startTime di ogni punto indica il giorno a cui è assegnato il conteggio. Nell'esempio, total del primo giorno è 412, ovvero 300 search più 112 maps.

Una metrica è null, non un array vuoto, quando la sede non ha dati di Google per l'intervallo o il suo profilo Google non è collegato. Gestisci null e [] allo stesso modo quando aggreghi i dati.

Leggi le metriche di Facebook per un intervallo di date

GET /locations/{locationId}/facebook-analytics ha la stessa struttura all'interno di data.facebookInsights, con cinque serie giornaliere. Richiede che la Pagina Facebook della sede sia collegata. ctaAction ti permette di misurare le interazioni con un pulsante "Prenota ora" o "Chiama ora" durante l'intervallo di una campagna.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/facebook-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "facebookInsights": {      "views": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 120 }],      "ctaAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 5 }],      "directionsAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 3 }],      "phoneAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 2 }],      "websiteAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 9 }]    }  }}

Non esiste una metrica per i Mi piace della Pagina. Ogni serie viene restituita come null quando la Pagina non ha dati per l'intervallo o non è collegata, quindi verifica la presenza di null prima di iterare.

Leggi le visualizzazioni su Bing per un intervallo di date

GET /locations/{locationId}/bing-analytics restituisce una singola serie, data.bingInsights.views, raggruppata per settimana anziché per giorno. Ogni punto rappresenta il conteggio delle visualizzazioni di una settimana a partire da startTime. I dati vengono aggiornati ogni lunedì per la settimana precedente, quindi la settimana completa più recente è l'ultima che vedrai. Recupera un intervallo di più mesi per ottenere una linea di tendenza; non è adatto all'attribuzione su base giornaliera.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bing-analytics?fromDate=2026-06-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "bingInsights": {      "views": [        { "startTime": "2026-06-01T00:00:00+00:00", "value": 73 },        { "startTime": "2026-06-08T00:00:00+00:00", "value": 58 }      ]    }  }}

A differenza di Google e Facebook, Bing segnala l'assenza di dati con un array views vuoto e un 200, non con null. Tratta entrambi i casi come "nulla da mostrare" e verifica la condizione length == 0 se vuoi un'etichetta "nessun dato", poiché la somma degli elementi di un array vuoto è 0.

Errori che vedrai

Le pagine di riferimento non indicano codici di errore specifici delle risorse per i dati analitici. I casi che incontrerai:

L'elenco completo si trova in Codici di errore.

Passaggi successivi

• Recupera i dati analitici del profilo: somma i valori di una serie per ottenere un totale mensile e confronta due periodi, con i controlli su null.
• Analisi delle recensioni: valutazione, volume e tasso di risposta per la stessa sede, con differenze tra periodi integrate.
• Recensioni: gli endpoint di analisi delle recensioni insieme al resto della risorsa delle recensioni.
• Pagina iniziale della documentazione di riferimento: Dati analitici. SDK: Dati analitici in Python, Dati analitici in Node.