Listings APIListings API
Se connecter

Avis

Récupérez des avis, répondez-y et analysez-les avec le SDK listingsapi-js.

Les avis (appelés « interactions » dans l’API) sont des notes en étoiles et des commentaires libres recueillis sur Google, Facebook et Yelp. Toutes les méthodes relatives aux avis sont disponibles sur l’instance du client ListingsAPI. Les opérations d’écriture qui échouent côté serveur lèvent une exception ValidationError ; vous n’avez donc jamais besoin de vérifier les indicateurs success dans les valeurs de retour.

fetchInteractions

Récupérez les avis d’un établissement avec des filtres facultatifs et une pagination par curseur. Les identifiants numériques des établissements sont encodés automatiquement.

TypeScript
// Single pageconst result = await client.fetchInteractions(16808, {first:         25,startDate:     '2026-01-01',endDate:       '2026-06-30',ratingFilters: [1, 2],}); if (!Array.isArray(result)) {console.log(result.interactions);   // Interaction[]console.log(result.totalCount);     // number | undefinedconsole.log(result.pageInfo);       // { hasNextPage, hasPreviousPage, startCursor, endCursor }} // All reviews at once, returns a flat Interaction[]const all = await client.fetchInteractions(16808, {fetchAll:  true,startDate: '2026-01-01',});

Options

ParamètreTypeDescription
firstnumberTaille des pages pour la pagination vers l’avant.
afterstringCurseur provenant d’un pageInfo.endCursor précédent.
beforestringCurseur pour la pagination vers l’arrière.
lastnumberTaille des pages pour la pagination vers l’arrière.
fetchAllbooleanParcourir automatiquement les pages et renvoyer un Interaction[] à un seul niveau.
pageSizenumberTaille des pages utilisée en interne lorsque fetchAll vaut true (valeur par défaut : 100).
startDatestringBorne inférieure, YYYY-MM-DD.
endDatestringBorne supérieure, YYYY-MM-DD.
categorystringFiltre par catégorie d’interaction.
siteUrlsstring[]Limiter à certains annuaires, e.g. ['maps.google.com'].
ratingFiltersnumber[]Notes en étoiles à conserver, e.g. [1, 2].

Valeurs de retour

Sans fetchAll, un objet InteractionResponse : success, interactions (Interaction[]), pageInfo (hasNextPage, hasPreviousPage, startCursor, endCursor), totalCount lorsque l’API en fournit un, et raw (les données brutes non analysées). Avec fetchAll: true, un Interaction[] à un seul niveau. Chaque Interaction contient id, content, rating, siteName, siteUrl, reviewerName, publishedAt, category et responses.

fetchReviewDetails

Récupérez des informations détaillées sur des avis précis à partir de leur identifiant d’interaction. Si le tableau d’entrée est vide, le traitement s’arrête immédiatement et renvoie un objet vide sans appel réseau.

TypeScript
const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);

respondToReview

Publiez une réponse à un avis. La transmission à l’annuaire source est asynchrone.

TypeScript
await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);
ParamètreTypeDescription
interactionIdstringIdentifiant d’interaction de l’avis.
responseContentstringTexte de la réponse à publier.

editReviewResponse

Modifiez une réponse existante.

TypeScript
await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);
ParamètreTypeDescription
reviewIdstringAvis auquel la réponse est associée.
responseIdstringRéponse à modifier.
responseContentstringNouveau texte de la réponse.

archiveReviewResponse

Archivez (masquez) une réponse.

TypeScript
await client.archiveReviewResponse('response-uuid');

Analyse des avis

Les trois méthodes d’analyse acceptent un identifiant d’établissement ainsi qu’une plage { startDate, endDate } facultative (YYYY-MM-DD) et renvoient un objet ReviewAnalytics dont la structure varie selon le point de terminaison.

fetchReviewAnalyticsOverview

Statistiques globales sur une période : agrégats des notes et du volume d’avis pour l’établissement.

TypeScript
const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});console.log(overview);

fetchReviewAnalyticsTimeline

Évolution du nombre d’avis et des notes, adaptée à la création de graphiques.

TypeScript
const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewAnalyticsSitesStats

Répartition des avis par site source (Google, Facebook, Yelp).

TypeScript
const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate:   '2026-06-30',});

fetchReviewPhrases

Analyse des expressions et des sentiments pour un ou plusieurs établissements sur une période. Accepte un seul objet d’options ; locationIds est obligatoire et une liste vide renvoie [] sans appel réseau.

TypeScript
const phrases = await client.fetchReviewPhrases({locationIds: ['TG9jYXRpb246MTY4MDg=', 'TG9jYXRpb246MTY4MDk='],startDate:   '2026-01-01',endDate:     '2026-06-30',siteUrls:    ['maps.google.com'],}); for (const p of phrases) {console.log(p.phrase, p.count, p.sentiment);}

Options

ParamètreTypeObligatoireDescription
locationIdsstring[]OuiIdentifiants d’établissements encodés en Base64.
startDatestringNonBorne inférieure, YYYY-MM-DD.
endDatestringNonBorne supérieure, YYYY-MM-DD.
siteUrlsstring[]NonLimiter à certains annuaires.

Paramètres des avis

fetchReviewSettings

Récupérez les paramètres des sources d’avis pour un établissement.

TypeScript
const settings = await client.fetchReviewSettings(16808);console.log(settings);

editReviewSettings

Définissez ou mettez à jour les URL des sources d’avis suivies pour un établissement. Chaque entrée est un ReviewSiteUrl contenant un name et un url.

TypeScript
await client.editReviewSettings(16808, [{ name: 'Google', url: 'https://www.google.com/maps/place/acme-dental' },{ name: 'Yelp',   url: 'https://www.yelp.com/biz/acme-dental-new-york' },]);
ParamètreTypeDescription
locationIdstring | numberLes identifiants numériques sont encodés automatiquement.
siteUrlsReviewSiteUrl[]Entrées de type { name, url } par source d’avis.

fetchReviewSiteConfig

Récupérez la liste des sources d’avis admissibles à l’échelle du compte. N’accepte aucun argument et renvoie un ReviewSiteConfig[].

TypeScript
const config = await client.fetchReviewSiteConfig();