Listings APIListings API
Entrar

Meça o desempenho das avaliações

Veja KPIs de avaliações de um local, trace a evolução diária, compare fontes, extraia frases comuns e receba resumos diários e semanais por webhook.

Três endpoints relacionados descrevem as avaliações de um local em números: uma visão geral dos KPIs, uma série diária e um detalhamento por fonte. Um quarto lista as expressões que os clientes repetem. Juntos, eles são suficientes para um cartão de indicadores, um gráfico de tendências e um painel de reclamações.

1. Consulte os KPIs de um local

GET /locations/{locationId}/review-analytics-overview retorna quatro estatísticas em data.interactionsAnalyticsStats.stats. O intervalo de datas é opcional aqui; ele restringe o período usado para calcular os valores e as variações.

Overview
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "interactionsAnalyticsStats": {      "stats": [        { "name": "total-reviews", "value": 128, "delta": 6.67 },        { "name": "new-reviews", "value": 9, "delta": -25 },        { "name": "overall-rating", "value": 4.43, "delta": 2.31 },        { "name": "review-response-rate", "value": 62.5, "delta": 12.5 }      ]    }  }}
namevalueInterprete como
total-reviewscontagemTodas as avaliações do local.
new-reviewscontagemAvaliações recebidas no período.
overall-rating1 a 5Nota média em estrelas.
review-response-rateporcentagemProporção de avaliações com uma resposta do proprietário.

Uma conta nova sem período anterior informa um delta de 100, então não interprete as variações do primeiro mês como crescimento.

2. Obtenha a série diária para um gráfico

GET .../review-analytics-timeline retorna uma entrada por dia em data.interactionsChartData.data. Sempre informe startDate e endDate, ou o serviço escolherá seu próprio período. Adicione site (um nome de host, como maps.google.com) para representar uma única fonte separadamente.

Timeline
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "interactionsChartData": {      "data": [        { "date": "2026-08-01", "interactionCount": 4, "averageRating": 4.5 },        { "date": "2026-08-02", "interactionCount": 0, "averageRating": null },        { "date": "2026-08-03", "interactionCount": 7, "averageRating": 4.285714285714286 }      ]    }  }}

Represente interactionCount como barras e averageRating como uma linha. averageRating é a média daquele dia, não uma média acumulada, e seu valor é null em dias sem avaliações, então deixe uma lacuna em vez de representar zero.

3. Detalhe por fonte

GET .../review-analytics-sites-stats retorna uma entrada por fonte de avaliações em data.interactionsSitesStats.stats. Use esse resultado para ver qual plataforma alterou a média.

By source
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-sites-stats?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "interactionsSitesStats": {      "stats": [        {          "key": "google",          "siteUrl": "maps.google.com",          "averageRating": { "value": 4.6, "delta": 2.2 },          "totalInteractions": { "value": 412, "delta": 6.1 },          "newInteractions": { "value": 24, "delta": 33.3 },          "recency": "2026-09-06T14:12:00Z",          "humanizedRecency": "3 days ago"        },        {          "key": "facebook",          "siteUrl": "facebook.com",          "averageRating": { "value": 4.1, "delta": -1.4 },          "newInteractions": { "value": 0, "delta": -100 },          "recency": null,          "humanizedRecency": null        }      ]    }  }}

averageRating, totalInteractions e newInteractions contêm, cada um, um value e um delta. Um averageRating.delta negativo ao lado de valores equivalentes estáveis aponta para uma plataforma; se todos forem negativos, isso aponta para a loja. Um newInteractions de 0 com um recency de meses atrás geralmente significa que a conexão com a fonte deixou de ser atualizada, então consulte Liste as fontes de avaliações de um local e adicione a fonte novamente usando Edite as configurações de avaliações se ela não estiver mais na lista.

4. Encontre as expressões que os clientes usam

GET /review-phrases retorna um array simples em data.newReviewPhrases, com uma entrada por expressão recorrente e a mesma estrutura de estatísticas da visão geral, calculadas apenas sobre as avaliações que contêm essa expressão. Adicione ratingFilters=[1,2] para um painel de reclamações. locationIds e ratingFilters são arrays JSON na string de consulta, então precisam ser codificados para URL; os SDKs fazem isso para você.

Phrases
curl -G "https://listingsapi.com/api/v4/review-phrases" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'locationIds=[1800289]' \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'startDate=2026-06-01' \--data-urlencode 'endDate=2026-08-31' \--data-urlencode 'phraseCount=10'
JSON
{  "data": {    "newReviewPhrases": [      {        "reviewPhrase": "long wait",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 11, "delta": 37.5, "abs": 3 },            { "name": "overall-rating", "value": 2.9, "delta": -8.4, "abs": -0.27 }          ]        }      }    ]  }}

total-reviews indica com que frequência a expressão aparece, overall-rating indica se essas avaliações expressam satisfação, e delta indica se a situação está piorando. abs é a variação absoluta apresentada junto à porcentagem. Os métodos de expressões dos SDKs não expõem ratingFilters nem phraseCount, então use a chamada REST quando precisar deles.

5. Receba retratos diários e semanais por webhook

Com uma URL de webhooks configurada, review_analytics.daily_snapshot e review_analytics.weekly_snapshot são disparados uma vez por local por período. Interprete cada um como o resultado do endpoint de visão geral calculado para um período fixo: total_reviews é total-reviews, new_reviews_in_period é new-reviews, e average_rating é overall-rating para esse período, com previous_average_rating para o período anterior. A taxa de resposta, a série diária e o detalhamento por fonte não estão no payload; chame os endpoints acima quando o evento chegar se precisar desses dados.

JSON
{  "event": "review_analytics.weekly_snapshot",  "timestamp": "2026-08-24T02:00:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "period": "2026-08-17",    "granularity": "weekly",    "total_reviews": 1237,    "new_reviews_in_period": 18,    "average_rating": 4.6123,    "previous_average_rating": 4.5901  }}

O volume dessa família de eventos cresce com o número de locais: 400 locais significam 400 eventos diários em uma rajada, e os eventos que excedem o limite por minuto do seu plano são descartados, não enfileirados. Portanto, a ausência de um retrato é ambígua. Nunca registre zero nesse caso; consulte novamente a visão geral para esse período. A configuração está em Reaja a eventos com webhooks.

Próximas etapas