Listings APIListings API
Entrar

Obtenha análises de perfis do Google, Facebook e Bing

Obtenha métricas diárias de perfis do Google e Facebook e visualizações semanais do Bing para um local, some a série mensal e compare dois períodos.

Os dados analíticos de perfis informam com que frequência um local foi visto e recebeu ações em cada plataforma de publicação: impressões, solicitações de rotas, chamadas e cliques no site. Cada métrica é uma série temporal de pontos { startTime, value }, portanto os totais que você exibe são calculados por você.

1. Leia métricas do Google para um intervalo de datas

GET /locations/{locationId}/google-analytics?fromDate=&toDate= retorna data.googleInsights com uma série diária por métrica. total corresponde às impressões do perfil, search mais maps; não inclui as métricas de ações.

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    }  }}
SérieSignificado
totalImpressões, search mais maps.
search, mapsImpressões no Google Search e no Google Maps.
directionsAction, phoneAction, websiteActionSolicitações de rotas, cliques para ligar, cliques no site.
businessBookings, businessFoodOrders, businessFoodMenuClicksReservas, pedidos de comida e cliques no cardápio, para perfis que oferecem essas opções.

Um id de local malformado retorna 200 com googleInsights: null e um array errors, o que se parece com um perfil desconectado. Verifique errors primeiro.

2. Leia métricas do Facebook

GET .../facebook-analytics tem a mesma estrutura em data.facebookInsights, com cinco séries diárias: 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 os cliques no botão de chamada para ação da Página, que é como você mede uma campanha de "Reserve agora" ou "Ligue agora". Não há métrica de curtidas na página.

3. Leia visualizações do Bing

GET .../bing-analytics retorna uma única série, data.bingInsights.views, agrupada por semana em vez de por dia. Os dados são atualizados toda segunda-feira com os dados da semana anterior, então consulte um intervalo de vários meses para obter uma linha de tendência.

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 }      ]    }  }}

Ao contrário do Google e do Facebook, o Bing indica a ausência de dados com um array views vazio em vez de null. Trate ambos como "nada a exibir".

4. Some uma série para obter um total mensal

Consulte o mês e depois some o value de cada ponto. Mantenha null distinto de zero: um perfil desconectado deve aparecer como "indisponível", não como um mês sem tráfego. A página de dados analíticos do Node SDK tem a mesma função auxiliar 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) }'

O Bing precisa de uma verificação adicional: a soma de um array views vazio resulta em 0, então verifique length == 0 se você quiser exibir "sem dados" nesse caso também.

5. Compare dois períodos

Consulte a mesma métrica para dois intervalos de igual duração e calcule a variação a partir dos dois totais. A API não tem comparação integrada para dados analíticos de perfis; os campos delta existem apenas nos dados analíticos de avaliações.

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'

Trate três casos: qualquer um dos períodos com null (não conectado), o período anterior com 0 (divisão por zero) e um intervalo ainda em andamento, pois um mês parcial comparado com um mês completo sempre parece indicar uma queda. Cada chamada conta para o seu limite de requisições, então armazene o período anterior em cache em vez de consultá-lo novamente a cada renderização.

Próximos passos