Análises

Todos os endpoints de análise de perfil com exemplos cURL, Python e Node: métricas diárias do Google/Facebook e visualizações semanais do Bing por local.

As estatísticas de perfil mostram com que frequência um local foi visto e recebeu interações em cada plataforma de publicação: impressões, visualizações de página, solicitações de rotas, chamadas e cliques no site. Há três endpoints, um por plataforma de publicação, e os três são de leitura, portanto, uma chave Read (leitura) é suficiente. Cada métrica é uma série temporal de pontos { startTime, value }; a API não retorna totais escalares, portanto, as somas que você exibe são calculadas por você.

Visão geral dos endpoints

Os três compartilham os mesmos parâmetros. fromDate e toDate são do tipo YYYY-MM-DD, ambos opcionais; se você os omitir, será usado o período recente padrão da plataforma de publicação. O caminho aceita o id Relay em base64 ou o número simples. Um valor que não seja nenhum dos dois faz a API retornar 200 com o objeto de insights definido como null e um array errors, o que se parece com um perfil desconectado, portanto, verifique errors primeiro.

Consulte métricas do Google para um intervalo de datas

GET /locations/{locationId}/google-analytics retorna data.googleInsights com uma série diária por métrica. total representa as impressões do perfil, search mais maps; não inclui as métricas de ações. Use essa métrica para um relatório de visibilidade antes e depois de uma alteração nos dados.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "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": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodOrders": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodMenuClicks": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }]    }  }}

O startTime de cada ponto é o dia em que a contagem é agrupada. No exemplo, total no primeiro dia é 412, ou seja, 300 de search mais 112 de maps.

Uma métrica é null, e não um array vazio, quando o local não tem dados do Google para o período ou seu perfil do Google não está conectado. Trate null e [] da mesma forma ao agregar os dados.

Consulte métricas do Facebook para um intervalo de datas

GET /locations/{locationId}/facebook-analytics tem a mesma estrutura em data.facebookInsights, com cinco séries diárias. Esse endpoint exige que a Página do Facebook do local esteja conectada. Com ctaAction, você mede o desempenho de um botão "Reserve agora" ou "Ligue agora" durante o período de uma campanha.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/facebook-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

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

Não há métrica de curtidas da página. Todas as séries retornam null quando a Página não tem dados para o intervalo ou não está conectada, portanto, verifique se o valor é null antes de iterar.

Consulte as visualizações do Bing em um intervalo de datas

GET /locations/{locationId}/bing-analytics retorna uma única série, data.bingInsights.views, agrupada por semana em vez de por dia. Cada ponto é a contagem de visualizações de uma semana que começa em startTime. Os dados são atualizados toda segunda-feira com os dados da semana anterior, portanto, a semana completa mais recente é a última que você verá. Consulte um intervalo de vários meses para obter uma linha de tendência; esses dados não são adequados para atribuição diária.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bing-analytics?fromDate=2026-06-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "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 acompanhado de 200, e não com null. Trate ambos como "nada para exibir" e verifique length == 0 se quiser exibir o rótulo "sem dados", pois a soma de um array vazio é 0.

Erros que você verá

As páginas de referência não indicam códigos de erro específicos do recurso de análise. Os casos que você encontrará:

A lista completa está em Códigos de erro.

Próximos passos

• Consulte os dados de análise do perfil: some uma série para obter um total mensal e compare dois períodos, com as verificações de null.
• Análise de avaliações: nota, volume e taxa de resposta para o mesmo local, com diferenças entre períodos já incluídas.
• Avaliações: os endpoints de análise de avaliações junto com o restante do recurso de avaliações.
• Página inicial da referência: Análise. SDKs: Análise em Python, Análise em Node.