Listings APIListings API
Accedi

Recupera le analisi dei profili Google, Facebook e Bing

Metriche giornaliere dei profili Google e Facebook e visualizzazioni settimanali Bing per sede: somma la serie mensile e confronta due periodi.

I dati analitici dei profili indicano quante volte una sede è stata visualizzata e quali azioni ha generato su ciascuna piattaforma di pubblicazione: impressioni, richieste di indicazioni stradali, chiamate e clic sul sito web. Ogni metrica è una serie temporale di punti { startTime, value }, quindi i totali che mostri sono quelli che calcoli tu.

1. Leggi le metriche di Google per un intervallo di date

GET /locations/{locationId}/google-analytics?fromDate=&toDate= restituisce data.googleInsights con una serie giornaliera per ogni metrica. total rappresenta le impressioni del profilo, search più maps; non include le metriche relative alle azioni.

Google
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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": null,      "businessFoodOrders": null,      "businessFoodMenuClicks": null    }  }}
SerieSignificato
totalImpressioni, search più maps.
search, mapsImpressioni in Google Search e in Google Maps.
directionsAction, phoneAction, websiteActionRichieste di indicazioni stradali, clic per chiamare, clic sul sito web.
businessBookings, businessFoodOrders, businessFoodMenuClicksPrenotazioni, ordini di cibo e clic sul menu, per i profili che li offrono.

Un ID della sede in un formato non valido fa sì che venga restituito 200 con googleInsights: null e un array errors, un risultato che sembra indicare un profilo non collegato. Controlla prima errors.

2. Leggi le metriche di Facebook

GET .../facebook-analytics ha la stessa struttura sotto data.facebookInsights, con cinque serie giornaliere: views, ctaAction, directionsAction, phoneAction e websiteAction.

Facebook
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/facebook-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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 }]    }  }}

ctaAction conta i clic sul pulsante di invito all'azione della Pagina, consentendoti di misurare una campagna "Prenota ora" o "Chiama ora". Non esiste una metrica per i Mi piace della pagina.

3. Leggi le visualizzazioni di Bing

GET .../bing-analytics restituisce una singola serie, data.bingInsights.views, raggruppata per settimana anziché per giorno. I dati vengono aggiornati ogni lunedì per la settimana precedente, quindi recupera un intervallo di più mesi per ottenere una linea di tendenza.

Bing
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bing-analytics?fromDate=2026-06-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "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 anziché con null. Tratta entrambi come "nessun dato da mostrare".

4. Somma una serie per ottenere un totale mensile

Recupera i dati del mese, poi somma il valore value di ogni punto. Mantieni null distinto da zero: un profilo non collegato deve essere indicato come "non disponibile", non come un mese senza traffico. La pagina dedicata ai dati analitici del Node SDK contiene la stessa funzione di utilità sumSeries.

Monthly total
# jq: null when the metric is null, otherwise the sum of valuescurl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.googleInsights | { search: (if .search == null then null else ([.search[].value] | add) end),                               maps: (if .maps == null then null else ([.maps[].value] | add) end) }'

Bing richiede un controllo aggiuntivo: la somma di un array views vuoto è 0, quindi verifica length == 0 se vuoi mostrare "nessun dato" anche in quel caso.

5. Confronta due periodi

Recupera la stessa metrica per due intervalli di uguale durata e calcola la variazione a partire dai due totali. L'API non offre un confronto integrato per i dati analitici dei profili; i campi delta esistono solo nei dati analitici delle recensioni.

Two periods
curl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-07-01&toDate=2026-07-31" \-H "Authorization: API $LISTINGSAPI_KEY" | jq '[.data.googleInsights.total[].value] | add' curl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY" | jq '[.data.googleInsights.total[].value] | add'

Gestisci tre casi: uno dei due periodi è null (profilo non collegato), il periodo precedente è 0 (divisione per zero) e un intervallo è ancora in corso, poiché un mese parziale confrontato con uno completo sembra sempre indicare un calo. Ogni chiamata viene conteggiata ai fini del limite di frequenza delle richieste, quindi memorizza nella cache il periodo precedente anziché recuperarlo a ogni rendering.

Passaggi successivi