Statistiques

Endpoints de statistiques de profil avec exemples cURL, Python et Node : métriques Google/Facebook par jour et vues Bing par semaine pour un établissement.

Les statistiques de profil indiquent à quelle fréquence un établissement a été vu et a suscité des actions sur chaque plateforme de publication : impressions, vues de page, demandes d’itinéraire, appels et clics vers le site web. Il existe trois endpoints, un par plateforme de publication, et tous sont en lecture seule ; une clé Read (lecture) suffit donc. Chaque métrique est une série temporelle de points { startTime, value } ; l’API ne renvoie aucun total scalaire, les sommes que vous affichez sont donc celles que vous calculez.

Aperçu des endpoints

Les trois endpoints utilisent les mêmes paramètres. fromDate et toDate sont de type YYYY-MM-DD et sont tous deux facultatifs ; si vous les omettez, la période récente par défaut de la plateforme de publication est utilisée. Le chemin accepte l’identifiant Relay en base64 ou le nombre brut. Si la valeur ne correspond à aucun de ces deux formats, l’endpoint renvoie 200 avec l’objet insights défini sur null et un tableau errors, ce qui ressemble au résultat obtenu pour un profil déconnecté ; vérifiez donc d’abord errors.

Lire les métriques Google pour une plage de dates

GET /locations/{locationId}/google-analytics renvoie data.googleInsights avec une série quotidienne par métrique. total correspond aux impressions du profil, soit search plus maps ; cette métrique n’inclut pas les métriques d’action. Utilisez-la pour établir un rapport de visibilité comparant les périodes avant et après une modification des données.

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

Le champ startTime de chaque point indique le jour auquel le décompte est rattaché. Dans l’exemple, total vaut 412 le premier jour, soit 300 pour search plus 112 pour maps.

Une métrique vaut null, et non un tableau vide, lorsque l’établissement ne dispose d’aucune donnée Google pour la période ou que son profil Google n’est pas connecté. Traitez null et [] de la même manière lors de l’agrégation.

Lire les métriques Facebook pour une plage de dates

GET /locations/{locationId}/facebook-analytics présente la même structure sous data.facebookInsights, avec cinq séries quotidiennes. Cet endpoint nécessite que la Page Facebook de l’établissement soit connectée. ctaAction vous permet de mesurer les clics sur un bouton « Réserver maintenant » ou « Appeler maintenant » pendant la période d’une campagne.

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

Il n’existe aucune métrique pour les mentions J’aime de la Page. Chaque série est renvoyée avec la valeur null lorsque la Page ne dispose d’aucune donnée pour la plage de dates ou qu’elle n’est pas connectée ; vérifiez donc la présence de null avant de parcourir la série.

Consulter les vues Bing sur une plage de dates

GET /locations/{locationId}/bing-analytics renvoie une seule série, data.bingInsights.views, regroupée par semaine plutôt que par jour. Chaque point correspond au nombre de vues d'une semaine commençant à startTime. Les données sont actualisées chaque lundi pour la semaine précédente ; la semaine complète la plus récente est donc la dernière que vous verrez. Récupérez une plage de plusieurs mois pour obtenir une courbe de tendance ; ces données ne conviennent pas à une attribution à l'échelle de la journée.

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

Contrairement à Google et Facebook, Bing signale l'absence de données par un tableau views vide avec un 200, et non par null. Traitez les deux cas comme « rien à afficher » et testez length == 0 si vous souhaitez afficher le libellé « aucune donnée », car la somme d'un tableau vide vaut 0.

Erreurs que vous rencontrerez

Les pages de référence ne mentionnent aucun code d'erreur propre aux ressources d'analyse. Voici les cas que vous rencontrerez :

La liste complète figure dans Codes d'erreur.

Étapes suivantes

• Récupérer les statistiques du profil : additionnez les valeurs d'une série pour obtenir un total mensuel et comparez deux périodes, en appliquant les vérifications null.
• Statistiques des avis : note, volume et taux de réponse pour le même établissement, avec calcul intégré des écarts entre périodes.
• Avis : les points de terminaison des statistiques des avis, aux côtés du reste de la ressource consacrée aux avis.
• Page d'accueil de la référence : Statistiques. SDK : Statistiques Python, Statistiques Node.