Listings APIListings API
Se connecter

Mesurer les performances des avis

Avis d’un établissement : KPI, courbe quotidienne, sources comparées, expressions fréquentes et bilans quotidiens et hebdomadaires par webhook.

Trois endpoints complémentaires décrivent les avis d'un établissement en chiffres : une vue d'ensemble des indicateurs clés, une chronologie quotidienne et une répartition par source. Un quatrième répertorie les expressions que les clients répètent. Ensemble, ils suffisent pour créer une vignette d'indicateurs, un graphique de tendance et un panneau de réclamations.

1. Consulter les indicateurs clés d'un établissement

GET /locations/{locationId}/review-analytics-overview renvoie quatre statistiques dans data.interactionsAnalyticsStats.stats. La plage de dates est facultative ici ; elle restreint la période sur laquelle les valeurs et les variations sont calculé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 }      ]    }  }}
namevalueÀ interpréter comme
total-reviewsnombreTous les avis de l'établissement.
new-reviewsnombreAvis reçus pendant la période.
overall-rating1 à 5Note moyenne en étoiles.
review-response-ratepourcentagePart des avis ayant reçu une réponse du propriétaire.

Un compte nouvellement créé, sans période antérieure, indique un delta de 100 ; n'interprétez donc pas les variations du premier mois comme une croissance.

2. Récupérer la chronologie quotidienne pour un graphique

GET .../review-analytics-timeline renvoie une entrée par jour dans data.interactionsChartData.data. Fournissez toujours startDate et endDate, sinon le service choisit lui-même sa période. Ajoutez site (un nom d'hôte tel que maps.google.com) pour représenter une seule source.

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

Représentez interactionCount par des barres et averageRating par une courbe. averageRating est la moyenne du jour, et non une moyenne cumulée, et vaut null les jours sans avis ; laissez donc un espace vide plutôt que de tracer une valeur nulle.

3. Ventiler les résultats par source

GET .../review-analytics-sites-stats renvoie une entrée par source d'avis dans data.interactionsSitesStats.stats. Utilisez-le pour déterminer quelle plateforme de publication a fait évoluer la moyenne.

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 et newInteractions contiennent chacun un value et un delta. Un seul averageRating.delta négatif, alors que les valeurs équivalentes restent stables, indique un problème lié à une plateforme de publication ; des valeurs toutes négatives indiquent un problème lié à l'établissement. Un newInteractions de 0 avec un recency datant de plusieurs mois signifie généralement que la connexion à la source n'est plus à jour ; consultez donc Lister les sources d'avis d'un établissement et ajoutez à nouveau la source avec Modifier les paramètres des avis si elle a disparu.

4. Trouver les expressions utilisées par les clients

GET /review-phrases renvoie un simple tableau dans data.newReviewPhrases, avec une entrée par expression récurrente et la même structure de statistiques que la vue d'ensemble, calculées uniquement sur les avis qui contiennent cette expression. Ajoutez ratingFilters=[1,2] pour un panneau de réclamations. locationIds et ratingFilters sont des tableaux JSON dans la chaîne de requête ; ils doivent donc être encodés pour l'URL ; les SDK s'en chargent pour vous.

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 indique la fréquence d'apparition de l'expression, overall-rating indique si ces avis expriment de la satisfaction et delta indique si la situation se dégrade. abs est la variation absolue, fournie en complément du pourcentage. Les méthodes des SDK consacrées aux expressions n'exposent ni ratingFilters ni phraseCount ; utilisez donc l'appel REST lorsque vous en avez besoin.

5. Recevoir des instantanés quotidiens et hebdomadaires par webhook

Lorsqu'une URL de webhooks est configurée, review_analytics.daily_snapshot et review_analytics.weekly_snapshot se déclenchent une fois par établissement et par période. Interprétez chacun comme le résultat de l'endpoint de vue d'ensemble calculé pour une période fixe : total_reviews correspond à total-reviews, new_reviews_in_period à new-reviews et average_rating à overall-rating pour cette période, avec previous_average_rating pour la période précédente. Le taux de réponse, la chronologie et la répartition par source ne figurent pas dans la charge utile ; appelez les endpoints ci-dessus à l'arrivée de l'événement si vous en avez besoin.

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

Le volume de cette famille d'événements est proportionnel à votre nombre d'établissements : 400 établissements représentent 400 événements quotidiens envoyés en rafale, et les événements qui dépassent le plafond par minute de votre forfait sont supprimés, et non mis en file d'attente. L'absence d'un instantané est donc ambiguë. N'enregistrez jamais une valeur nulle pour cet instantané manquant ; récupérez à nouveau la vue d'ensemble pour cette période. La configuration est décrite dans Réagir aux événements avec des webhooks.

Étapes suivantes