Reviews
Fetch, respond to, and analyze reviews with the listingsapi-js SDK.
Reviews (called "interactions" in the API) are star ratings and free-form
feedback collected from Google, Facebook and Yelp. All review methods live directly on the ListingsAPI client instance.
Mutations that fail server-side throw a ValidationError, so you never need
to check success flags on the return values.
fetchInteractions
Fetch reviews for a location with optional filters and cursor-based pagination. Numeric location IDs are encoded automatically.
// 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
Returns
Without fetchAll, an InteractionResponse object: success, interactions
(Interaction[]), pageInfo (hasNextPage, hasPreviousPage, startCursor,
endCursor), totalCount when the API reports one, and raw (the unparsed
payload). With fetchAll: true, a flat Interaction[]. Each Interaction
carries id, content, rating, siteName, siteUrl, reviewerName,
publishedAt, category, and responses.
fetchReviewDetails
Fetch detailed information for specific reviews by interaction ID. An empty input array short-circuits and returns an empty object without a network call.
const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);respondToReview
Post a reply to a review. Delivery to the source directory is asynchronous.
await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);editReviewResponse
Edit an existing reply.
await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);archiveReviewResponse
Archive (hide) a reply.
await client.archiveReviewResponse('response-uuid');Review analytics
All three analytics methods take a location ID plus an optional
{ startDate, endDate } range (YYYY-MM-DD) and return a ReviewAnalytics
object whose shape varies by endpoint.
fetchReviewAnalyticsOverview
Overall stats for a date range: rating and volume rollups for the location.
const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});console.log(overview);fetchReviewAnalyticsTimeline
Review counts and ratings over time, suitable for charting.
const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewAnalyticsSitesStats
Review breakdown by source site (Google, Facebook, Yelp).
const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewPhrases
Phrase and sentiment analysis across one or more locations for a date range.
Takes a single options object; locationIds is required and an empty list
returns [] without a network call.
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
Review settings
fetchReviewSettings
Get review source settings for a location.
const settings = await client.fetchReviewSettings(16808);console.log(settings);editReviewSettings
Set or update the review source URLs tracked for a location. Each entry is a
ReviewSiteUrl with a name and a 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
Get the account-wide list of eligible review sources. Takes no arguments and
returns a ReviewSiteConfig[].
const config = await client.fetchReviewSiteConfig();