Analítica

Obtén datos de analítica de perfiles de Google, Bing y Facebook con el SDK listingsapi-js.

Los métodos de analítica obtienen estadísticas de cada plataforma, como impresiones en búsquedas, clics, solicitudes de indicaciones y llamadas telefónicas, de Google Business Profile, Bing Places y Facebook Pages. Todos los métodos de analítica están disponibles directamente en la instancia del cliente ListingsAPI y su alcance se limita a un ID de ubicación. Los ID numéricos de ubicación se codifican automáticamente, por lo que 16808 y 'TG9jYXRpb246MTY4MDg=' son intercambiables.

Los tres métodos comparten la misma firma: un ID de ubicación y un intervalo { fromDate, toDate } opcional. Ambas fechas son opcionales, tanto por separado como en conjunto; omítelas para usar el periodo de informes predeterminado de la plataforma.

Cada métrica es una serie temporal

Estos cuerpos de respuesta no contienen totales escalares. Cada métrica es un array de puntos { startTime, value }, uno por día (por semana en Bing), y una métrica para la que no tienes datos es null en lugar de 0 o []. Por tanto, suma tú los valores de la serie y distingue entre "sin datos" y "cero":

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

Obtén estadísticas de Google Business Profile para una ubicación.

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);

Opciones

El cuerpo de la respuesta es el objeto googleInsights, y cada una de sus claves contiene una serie { startTime, value }[]: total, search, maps, websiteAction, directionsAction, phoneAction, businessBookings, businessFoodOrders y businessFoodMenuClicks. total representa las impresiones del perfil, search más maps; no incluye las métricas de acciones. Cualquier serie para la que Google no tenga datos se devuelve como null. Consulta Obtener analítica de Google para una ubicación para ver la referencia completa de los campos.

fetchBingAnalytics

Obtén estadísticas de Bing Places para una ubicación.

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

Bing proporciona una única métrica, views, agrupada por semana en lugar de por día.

Opciones

fetchFacebookAnalytics

Obtén estadísticas de la página de Facebook para una ubicación.

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

El cuerpo de la respuesta de Facebook contiene views, ctaAction, websiteAction, directionsAction y phoneAction. No contiene pageLikes.

Opciones

Informe de varias plataformas

Consulta las tres plataformas en paralelo 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);

Si un perfil no está conectado a una plataforma determinada, la promesa del método se resuelve con un objeto vacío en lugar de rechazarse, y cada serie individual se devuelve como null. Indícalo como "no disponible" en lugar de convertirlo a 0 mediante ??; de lo contrario, un perfil desconectado aparecerá como un cero real en tu panel. Los fallos de las solicitudes siguen lanzando los errores tipados del SDK.

Recursos relacionados

• Ubicaciones: consulta los ID de ubicación
• Reseñas: analítica de reseñas (overview, timeline, sites-stats)
• Casos de uso: ejemplo práctico de un informe de analítica