Obtenir les avis d’un établissement ou de tout votre compte

Listez les avis récents d’un établissement, filtrez les mauvaises notes sans réponse, paginez par curseurs, explorez le compte et soyez alerté par webhook.

Les avis sont appelés interactions dans l'API. Tous les avis provenant de Google, Facebook ou Yelp sont renvoyés dans une seule liste par établissement et dans une vue agrégée pour le compte, de sorte qu'une seule intégration couvre toutes les sources que vous connectez.

1. Lister les derniers avis d'un établissement

GET /locations/{locationId}/reviews est une connexion paginée par curseur accessible à data.interactions. Les résultats sont renvoyés du plus récent au plus ancien, et first vaut 20 par défaut ; un seul appel ne renvoie donc jamais l'historique complet. Le chemin accepte l'id en base64 ou le nombre brut.

Latest reviews

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=10" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

Lisez data.interactions.edges[].node. id est un UUID brut, et non un id Relay en base64 ; c'est la valeur que vous transmettez lorsque vous répondez. totalCount correspond au nombre de correspondances dans l'ensemble des résultats, et non sur cette seule page. canRespond indique si cette source accepte les réponses du propriétaire via l'API.

2. Filtrer les avis à faible note sans réponse

Les filtres de type tableau sont des chaînes JSON dans la chaîne de requête : ratingFilters=[1,2] conserve les avis à 1 et 2 étoiles, et responseStatus=["PENDING"] conserve les avis sans réponse du propriétaire. Les crochets et les guillemets doivent être encodés pour une URL ; l'exemple cURL utilise donc -G avec --data-urlencode, qui encode chaque valeur et l'ajoute à l'URL pour vous. La chaîne de requête littérale équivalente est ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5D.

Unanswered 1-2 stars

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

Les filtres que vous pouvez combiner :

Paramètre	Valeurs	Remarques
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	Noms d'hôte obtenus via Lister les sources d'avis d'un compte.
`ratingFilters`	`[1,2]` et ainsi de suite	Notes en étoiles à conserver.
`responseStatus`	`["PENDING"]` ou `["RESPONDED"]`	Indique si une réponse du propriétaire existe.
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	Par défaut, les résultats sont classés du plus récent au plus ancien.
`startDate`, `endDate`	`YYYY-MM-DD`	Chaînes simples, et non JSON.
`searchString`	texte libre	Recherche en texte intégral dans le corps de l'avis.

3. Parcourir les pages à l'aide de curseurs

Transmettez la valeur de pageInfo.endCursor dans after lors de l'appel suivant. Arrêtez-vous lorsque hasNextPage vaut false ou qu'une page renvoie un tableau edges vide ; si une limite de page tombe sur l'avis le plus ancien, une page vide suit. Les 2 SDK peuvent lire les pages pour vous.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=50&after=SW50ZXJhY3Rpb246MV8xNTU0..." \-H "Authorization: API $LISTINGSAPI_KEY"

Chaque requête est comptabilisée dans votre limite de débit, et un établissement comptant 425 avis nécessite 9 appels avec first=50. En cas de 429, attendez Retry-After avant de demander la page suivante. Pour une synchronisation planifiée, délimitez l'exécution avec startDate et endDate au lieu de relire l'historique. Consultez Limites de débit.

4. Parcourir l'ensemble du compte avec la vue agrégée

GET /rollup_interactions renvoie les mêmes nœuds pour tous les établissements auxquels la clé donne accès, à data.rollupInteractions, avec un locationId sur chaque nœud. Il accepte les mêmes filtres ainsi que tag, dont la valeur par défaut est all. Il n'existe aucun filtre par établissement ; regroupez vous-même les résultats par locationId. Aucun des 2 SDK ne propose encore de méthode pour cet endpoint ; les exemples des SDK l'appellent donc avec requests et fetch.

Account-wide pending

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

Chaque nœud a la même structure qu'à l'étape 1, avec en plus un locationId numérique, qui correspond au databaseId du magasin. Le pageInfo de la vue agrégée peut omettre endCursor ; utilisez donc le cursor du dernier élément edge comme after, les 2 valeurs étant équivalentes.

5. Récupérer les détails complets par id

Lorsque vous avez enregistré des id, GET /reviewDetails renvoie des copies à jour sans pagination. interactionIds est un tableau JSON, encodé pour une URL comme les autres filtres. La réponse est un simple tableau à data.interactionDetails.interactions, et chaque interaction inclut son responses.

Details by id

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

JSON

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",          "responded": true,          "responseCount": 1,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED"            }          ]        }      ]    }  }}

Si vous fournissez un id provenant d'un autre compte, l'endpoint renvoie 200 avec interactionDetails: null et une erreur SY90001 ; vérifiez donc la présence de null avant d'accéder aux éléments par leur indice.

6. Recevoir des événements webhook au lieu d'effectuer des interrogations périodiques

Lorsqu'une URL de webhooks est configurée, un événement interaction.review est déclenché lorsqu'un avis est ingéré ou modifié. Les champs de l'avis se trouvent sous data.interaction, et non directement sous data, et data.interaction.id correspond au même UUID que celui renvoyé par la liste.

Deux points de vigilance. location_id est transmis sans normalisation dans cet événement : sa valeur peut être une chaîne numérique ou null, alors convertissez-la vous-même plutôt que de vous fier au type. Et le même id est reçu à nouveau chaque fois que l'avis change, alors traitez l'événement comme un signal invitant à relire l'avis, et non comme une insertion unique. La livraison ne fait l'objet que d'une seule tentative, sans nouvelle tentative en cas d'échec, alors conservez le balayage périodique de l'étape 4 comme filet de sécurité. La configuration est décrite dans Réagir aux événements avec des webhooks.

Étapes suivantes

Répondre aux avis : répondez aux avis en attente que vous venez de trouver, puis modifiez ou archivez la réponse.
Analyse des avis : note, volume et taux de réponse pour le même établissement.
Référence : Lister les interactions, Obtenir les interactions agrégées, Obtenir les interactions par identifiant, Attributs des interactions.
SDK : Avis avec Python, Avis avec Node.