Análises

Obtenha dados de análise dos perfis do Google, Bing e Facebook com o SDK listingsapi-js.

Os métodos de análise recuperam dados por plataforma, como impressões em pesquisas, cliques, solicitações de rotas e chamadas telefônicas, do Google Business Profile, do Bing Places e do Facebook Pages. Todos os métodos de análise estão disponíveis diretamente na instância do cliente ListingsAPI e têm seu escopo limitado a um ID de local. Os IDs numéricos de locais são codificados automaticamente, portanto 16808 e 'TG9jYXRpb246MTY4MDg=' podem ser usados de forma intercambiável.

Os três métodos compartilham a mesma assinatura: um ID de local e um intervalo { fromDate, toDate } opcional. As duas datas são opcionais, individualmente ou em conjunto; omita-as para usar o período padrão dos relatórios da plataforma.

Cada métrica é uma série temporal

Não há totais escalares nesses payloads. Cada métrica é um array de pontos { startTime, value }, um por dia (por semana no Bing), e uma métrica para a qual você não tem dados é null em vez de 0 ou []. Portanto, some os valores da série e mantenha a distinção entre "sem dados" 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

Busque dados analíticos do Google Business Profile para um local.

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

Opções

O payload é o objeto googleInsights, e cada chave nele é uma série { startTime, value }[]: total, search, maps, websiteAction, directionsAction, phoneAction, businessBookings, businessFoodOrders e businessFoodMenuClicks. total representa as impressões do perfil, a soma de search e maps; não inclui as métricas de ações. Qualquer série para a qual o Google não tenha dados é retornada como null. Consulte Obter dados analíticos do Google para um local para ver a referência completa dos campos.

fetchBingAnalytics

Busque dados analíticos do Bing Places para um local.

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

O Bing informa uma única métrica, views, agrupada por semana em vez de por dia.

Opções

fetchFacebookAnalytics

Busque dados analíticos da página do Facebook para um local.

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

O payload do Facebook contém views, ctaAction, websiteAction, directionsAction e phoneAction. Não há pageLikes.

Opções

Relatório de várias plataformas

Busque dados das três plataformas em paralelo com 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 um perfil não estiver conectado a uma determinada plataforma, o método resolve a promessa com um objeto vazio em vez de rejeitá-la, e uma série individual é retornada como null. Informe esse resultado como "indisponível" em vez de convertê-lo em 0 com ??, caso contrário, um perfil desconectado aparecerá como um zero real no seu painel. Falhas nas requisições continuam lançando os erros tipados do SDK.

Recursos relacionados

• Locais: consultar IDs de locais
• Avaliações: dados analíticos de avaliações (overview, timeline, sites-stats)
• Casos de uso: exemplo de implementação de relatório analítico