评价
使用 listingsapi-js SDK 获取、回复和分析评价。
评价（在 API 中称为“interactions”）是从 Google、Facebook 和 Yelp 收集的星级评分和自由格式反馈。所有评价方法都位于 ListingsAPI 客户端实例上。在服务器端失败的写入操作会抛出 ValidationError，因此您无需检查返回值中的 success 标志。
fetchInteractions
获取某个地点的评价，支持可选筛选条件和基于游标的分页。数字形式的地点 ID 会自动编码。
// 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',});选项
返回值
未使用 fetchAll 时，返回一个 InteractionResponse 对象：success、interactions（Interaction[]）、pageInfo（hasNextPage、hasPreviousPage、startCursor、endCursor）、API 报告时包含的 totalCount，以及 raw（未经解析的载荷）。使用 fetchAll: true 时，返回扁平的 Interaction[]。每个 Interaction 都包含 id、content、rating、siteName、siteUrl、reviewerName、publishedAt、category 和 responses。
fetchReviewDetails
通过互动 ID 获取指定评价的详细信息。如果输入数组为空，则直接返回空对象，不发起网络调用。
const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);respondToReview
发布对某条评价的回复。回复会异步发送到来源目录。
await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);editReviewResponse
编辑现有回复。
await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);archiveReviewResponse
归档（隐藏）回复。
await client.archiveReviewResponse('response-uuid');评价分析
这 3 个分析方法均接受一个地点 ID 和可选的 { startDate, endDate } 范围（YYYY-MM-DD），并返回一个 ReviewAnalytics 对象，其结构因端点而异。
fetchReviewAnalyticsOverview
指定日期范围内的总体统计数据：该地点的评分和评价数量汇总。
const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});console.log(overview);fetchReviewAnalyticsTimeline
评价数量和评分随时间的变化，适合用于绘制图表。
const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewAnalyticsSitesStats
按来源网站（Google、Facebook、Yelp）细分的评价数据。
const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewPhrases
分析一个或多个地点在指定日期范围内的短语和情感。接受单个选项对象；locationIds 为必填项，列表为空时返回 []，不发起网络调用。
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);}选项
评价设置
fetchReviewSettings
获取某个地点的评价来源设置。
const settings = await client.fetchReviewSettings(16808);console.log(settings);editReviewSettings
设置或更新某个地点所跟踪的评价来源 URL。每个条目都是一个 ReviewSiteUrl，包含一个 name 和一个 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
获取整个账户范围内符合条件的评价来源列表。不接受任何参数，返回一个 ReviewSiteConfig[]。
const config = await client.fetchReviewSiteConfig();