Recensioni

Recupera le recensioni, rispondi e analizzale con l'SDK listingsapi-js.

Le recensioni (chiamate "interactions" nell'API) sono valutazioni a stelle e commenti a testo libero raccolti da Google, Facebook e Yelp. Tutti i metodi per le recensioni sono disponibili nell'istanza del client ListingsAPI. Le operazioni di scrittura che falliscono lato server generano un'eccezione ValidationError, quindi non devi mai controllare i flag success nei valori restituiti.

fetchInteractions

Recupera le recensioni di una sede con filtri facoltativi e paginazione basata su cursore. Gli ID numerici delle sedi vengono codificati automaticamente.

// 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',});

Opzioni

Valori restituiti

Senza fetchAll, un oggetto InteractionResponse: success, interactions (Interaction[]), pageInfo (hasNextPage, hasPreviousPage, startCursor, endCursor), totalCount quando l'API ne segnala uno e raw (il payload non analizzato). Con fetchAll: true, un Interaction[] con struttura piatta. Ogni Interaction contiene id, content, rating, siteName, siteUrl, reviewerName, publishedAt, category e responses.

fetchReviewDetails

Recupera informazioni dettagliate su recensioni specifiche tramite l'ID dell'interazione. Se l'array di input è vuoto, l'esecuzione termina immediatamente e restituisce un oggetto vuoto senza effettuare una chiamata di rete.

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

respondToReview

Pubblica una risposta a una recensione. L'invio alla directory di origine è asincrono.

await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);

editReviewResponse

Modifica una risposta esistente.

await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);

archiveReviewResponse

Archivia (nasconde) una risposta.

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

Analisi delle recensioni

Tutti e tre i metodi di analisi accettano un ID di sede e un intervallo { startDate, endDate } facoltativo (YYYY-MM-DD) e restituiscono un oggetto ReviewAnalytics la cui struttura varia in base all'endpoint.

fetchReviewAnalyticsOverview

Statistiche complessive per un intervallo di date: dati aggregati sulle valutazioni e sul numero di recensioni della sede.

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

fetchReviewAnalyticsTimeline

Numero di recensioni e valutazioni nel tempo, adatti alla creazione di grafici.

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

fetchReviewAnalyticsSitesStats

Ripartizione delle recensioni per sito di origine (Google, Facebook, Yelp).

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

fetchReviewPhrases

Analisi delle espressioni e del sentiment per una o più sedi in un intervallo di date. Accetta un unico oggetto di opzioni; locationIds è obbligatorio e un elenco vuoto restituisce [] senza effettuare una chiamata di rete.

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

Opzioni

Impostazioni delle recensioni

fetchReviewSettings

Recupera le impostazioni delle fonti delle recensioni per una sede.

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

editReviewSettings

Imposta o aggiorna gli URL delle fonti delle recensioni monitorate per una sede. Ogni voce è un ReviewSiteUrl con un name e un url.

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' },]);

fetchReviewSiteConfig

Recupera l'elenco delle fonti delle recensioni idonee per l'intero account. Non accetta argomenti e restituisce un ReviewSiteConfig[].

const config = await client.fetchReviewSiteConfig();

Risorse correlate

• Sedi: cerca gli ID delle sedi
• Analisi: analisi dei profili Google, Bing e Facebook
• Casi d'uso: procedure per monitorare le recensioni e rispondere in blocco