Analisi

Recupera i dati di analisi dei profili Google, Bing e Facebook con l'SDK listingsapi-js.

I metodi di analisi recuperano statistiche a livello di piattaforma, come impressioni nelle ricerche, clic, richieste di indicazioni stradali e telefonate, da Google Business Profile, Bing Places e Facebook Pages. Tutti i metodi di analisi sono disponibili direttamente sull'istanza del client ListingsAPI e hanno come ambito un ID sede. Gli ID sede numerici vengono codificati automaticamente, quindi 16808 e 'TG9jYXRpb246MTY4MDg=' sono intercambiabili.

Tutti e tre i metodi hanno la stessa firma: un ID sede e un intervallo { fromDate, toDate } facoltativo. Entrambe le date sono facoltative, singolarmente o insieme; omettile per usare il periodo di riferimento predefinito della piattaforma.

Ogni metrica è una serie temporale

Questi payload non contengono totali scalari. Ogni metrica è un array di punti { startTime, value }, uno al giorno (alla settimana per Bing), e una metrica per cui non hai dati è null anziché 0 o []. Calcola quindi la somma della serie e mantieni la distinzione tra "nessun dato" e "zero":

type Point = { startTime: string; value: number | null }; // null when the metric is absent, so an empty profile never reads as 0.function sumSeries(series: Point[] | null | undefined): number | null {if (!Array.isArray(series)) return null;return series.reduce((acc, p) => acc + (p.value ?? 0), 0);} function show(label: string, series: Point[] | null | undefined) {const total = sumSeries(series);console.log(label, total === null ? 'unavailable' : total);}

fetchGoogleAnalytics

Recupera le statistiche di Google Business Profile per una sede.

const google = await client.fetchGoogleAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Impressions (total)', google.total);show('Search impressions', google.search);show('Maps impressions', google.maps);show('Website clicks', google.websiteAction);

Opzioni

Il payload è l'oggetto googleInsights e ogni sua chiave corrisponde a una serie { startTime, value }[]: total, search, maps, websiteAction, directionsAction, phoneAction, businessBookings, businessFoodOrders e businessFoodMenuClicks. total rappresenta le impressioni del profilo, cioè search più maps; non include le metriche relative alle azioni. Qualsiasi serie per cui Google non dispone di dati viene restituita come null. Consulta Recupera le statistiche di Google per una sede per la documentazione completa dei campi.

fetchBingAnalytics

Recupera le statistiche di Bing Places per una sede.

const bing = await client.fetchBingAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Bing views', bing.views);

Bing fornisce una sola metrica, views, raggruppata per settimana anziché per giorno.

Opzioni

fetchFacebookAnalytics

Recupera le statistiche della pagina Facebook per una sede.

const facebook = await client.fetchFacebookAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Page views', facebook.views);show('CTA clicks', facebook.ctaAction);

Il payload di Facebook contiene views, ctaAction, websiteAction, directionsAction e phoneAction. Non contiene pageLikes.

Opzioni

Report su più piattaforme

Recupera i dati da tutte e tre le piattaforme in parallelo con Promise.all:

import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from envconst LOCATION_ID = 16808;const range = { fromDate: '2024-01-01', toDate: '2024-12-31' }; const [google, bing, facebook] = await Promise.all([client.fetchGoogleAnalytics(LOCATION_ID, range),client.fetchBingAnalytics(LOCATION_ID, range),client.fetchFacebookAnalytics(LOCATION_ID, range),]); show('Google impressions:', google.total);show('Bing views:', bing.views);show('Facebook views:', facebook.views);

Se un profilo non è collegato per una determinata piattaforma, il metodo risolve la promessa con un oggetto vuoto anziché rifiutarla, e una singola serie viene restituita come null. Indica questo risultato come "non disponibile" anziché convertirlo in 0 con ??, altrimenti un profilo scollegato apparirà come uno zero effettivo nella tua dashboard. Le richieste non riuscite continuano a generare gli errori tipizzati dell'SDK.

Risorse correlate

• Sedi: cerca gli ID sede
• Recensioni: analisi delle recensioni (overview, timeline, sites-stats)
• Casi d'uso: procedura per creare un report di analisi