Reseñas
Obtén reseñas, respóndelas y analízalas con el SDK listingsapi-js.
Las reseñas (denominadas "interactions" en la API) son valoraciones con estrellas y comentarios de texto libre recopilados de Google, Facebook y Yelp. Todos los métodos de reseñas están disponibles en la instancia del cliente ListingsAPI. Las operaciones de escritura que fallan en el servidor lanzan un ValidationError, por lo que nunca necesitas comprobar los indicadores success en los valores devueltos.
fetchInteractions
Obtén las reseñas de una ubicación con filtros opcionales y paginación basada en cursores. Los ID numéricos de las ubicaciones se codifican automáticamente.
// 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',});Opciones
Valores devueltos
Sin fetchAll, un objeto InteractionResponse: success, interactions (Interaction[]), pageInfo (hasNextPage, hasPreviousPage, startCursor, endCursor), totalCount cuando la API lo indica y raw (el contenido sin analizar). Con fetchAll: true, un Interaction[] plano. Cada Interaction contiene id, content, rating, siteName, siteUrl, reviewerName, publishedAt, category y responses.
fetchReviewDetails
Obtén información detallada de reseñas específicas mediante su ID de interacción. Si el array de entrada está vacío, el método devuelve inmediatamente un objeto vacío sin realizar una llamada de red.
const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);respondToReview
Publica una respuesta a una reseña. El envío al directorio de origen es asíncrono.
await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);editReviewResponse
Edita una respuesta existente.
await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);archiveReviewResponse
Archiva (oculta) una respuesta.
await client.archiveReviewResponse('response-uuid');Análisis de reseñas
Los tres métodos de análisis aceptan un ID de ubicación y un intervalo opcional de { startDate, endDate } (YYYY-MM-DD), y devuelven un objeto ReviewAnalytics cuya estructura varía según el endpoint.
fetchReviewAnalyticsOverview
Estadísticas generales para un intervalo de fechas: datos agregados de valoraciones y volumen de reseñas de la ubicación.
const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});console.log(overview);fetchReviewAnalyticsTimeline
Recuentos de reseñas y valoraciones a lo largo del tiempo, adecuados para generar gráficos.
const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewAnalyticsSitesStats
Desglose de reseñas por sitio de origen (Google, Facebook, Yelp).
const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewPhrases
Análisis de frases y sentimiento en una o más ubicaciones para un intervalo de fechas. Acepta un único objeto de opciones; locationIds es obligatorio y una lista vacía devuelve [] sin realizar una llamada de red.
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);}Opciones
Configuración de reseñas
fetchReviewSettings
Obtén la configuración de las fuentes de reseñas de una ubicación.
const settings = await client.fetchReviewSettings(16808);console.log(settings);editReviewSettings
Establece o actualiza las URL de las fuentes de reseñas que se supervisan para una ubicación. Cada entrada es un ReviewSiteUrl con un name y 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
Obtén la lista de fuentes de reseñas admitidas para toda la cuenta. No acepta argumentos y devuelve un ReviewSiteConfig[].
const config = await client.fetchReviewSiteConfig();Recursos relacionados
- Ubicaciones: consulta los ID de las ubicaciones
- Análisis: análisis de perfiles de Google, Bing y Facebook
- Casos de uso: ejemplos prácticos para supervisar reseñas y responder en lote