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, Yelp, and the rest of the directory graph. 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 page
const 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 | undefined
console.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, and so on).

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

Related resources

• Locations: look up location IDs
• Analytics: Google, Bing, and Facebook profile analytics
• Use cases: review monitoring and bulk-respond recipes