衡量评价表现
读取地点的评价 KPI、绘制每日时间线、比较来源、挖掘常见短语，并通过 webhook 接收每日和每周快照。
3 个同类端点以数值形式描述地点的评价：KPI 概览、每日时间线和按来源细分的数据。第 4 个端点列出客户反复使用的短语。这些数据足以构建指标卡片、趋势图和投诉面板。
1. 读取地点的 KPI
GET /locations/{locationId}/review-analytics-overview 在 data.interactionsAnalyticsStats.stats 中返回 4 项统计数据。此处的日期范围是可选的，用于缩小计算数值及其变化量的时间窗口。
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "interactionsAnalyticsStats": { "stats": [ { "name": "total-reviews", "value": 128, "delta": 6.67 }, { "name": "new-reviews", "value": 9, "delta": -25 }, { "name": "overall-rating", "value": 4.43, "delta": 2.31 }, { "name": "review-response-rate", "value": 62.5, "delta": 12.5 } ] } }}没有上一时段数据的新账户，其 delta 会报告为 100，因此请勿将第 1 个月的变化量解读为增长。
2. 获取每日时间线以绘制图表
GET .../review-analytics-timeline 在 data.interactionsChartData.data 中按天返回条目，每天 1 条。请始终传入 startDate 和 endDate，否则服务会自行选择时间窗口。添加 site（主机名，例如 maps.google.com），即可单独绘制某个来源的数据。
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "interactionsChartData": { "data": [ { "date": "2026-08-01", "interactionCount": 4, "averageRating": 4.5 }, { "date": "2026-08-02", "interactionCount": 0, "averageRating": null }, { "date": "2026-08-03", "interactionCount": 7, "averageRating": 4.285714285714286 } ] } }}将 interactionCount 绘制为柱形，将 averageRating 绘制为折线。averageRating 是当天的平均值，而非累计平均值，在没有评价的日期其值为 null，因此请留出空缺，不要绘制为 0。
3. 按来源细分
GET .../review-analytics-sites-stats 在 data.interactionsSitesStats.stats 中按评价来源返回条目，每个来源 1 条。您可以据此查看哪个平台影响了平均值。
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-sites-stats?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"{ "data": { "interactionsSitesStats": { "stats": [ { "key": "google", "siteUrl": "maps.google.com", "averageRating": { "value": 4.6, "delta": 2.2 }, "totalInteractions": { "value": 412, "delta": 6.1 }, "newInteractions": { "value": 24, "delta": 33.3 }, "recency": "2026-09-06T14:12:00Z", "humanizedRecency": "3 days ago" }, { "key": "facebook", "siteUrl": "facebook.com", "averageRating": { "value": 4.1, "delta": -1.4 }, "newInteractions": { "value": 0, "delta": -100 }, "recency": null, "humanizedRecency": null } ] } }}averageRating、totalInteractions 和 newInteractions 各自包含一个 value 和一个 delta。如果某个平台的 averageRating.delta 为负，而其他平台保持不变，则问题指向该平台；如果所有平台均为负，则问题指向门店。如果 newInteractions 为 0，且 recency 已是数月前的值，通常表示来源连接已失效，因此请查看列出地点的评价来源，如果该来源已不存在，请通过编辑评价设置重新添加。
4. 查找客户使用的短语
GET /review-phrases 在 data.newReviewPhrases 中返回一个普通数组，每个反复出现的短语对应 1 个条目，其统计数据结构与概览相同，但仅根据包含该短语的评价计算。添加 ratingFilters=[1,2] 即可构建投诉面板。locationIds 和 ratingFilters 是查询字符串中的 JSON 数组，因此必须做 URL 编码；SDK 会自动完成。
curl -G "https://listingsapi.com/api/v4/review-phrases" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'locationIds=[1800289]' \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'startDate=2026-06-01' \--data-urlencode 'endDate=2026-08-31' \--data-urlencode 'phraseCount=10'{ "data": { "newReviewPhrases": [ { "reviewPhrase": "long wait", "phraseStats": { "stats": [ { "name": "total-reviews", "value": 11, "delta": 37.5, "abs": 3 }, { "name": "overall-rating", "value": 2.9, "delta": -8.4, "abs": -0.27 } ] } } ] }}total-reviews 表示短语出现的频率，overall-rating 表示这些评价是否表达了满意，delta 表示情况是否正在恶化。abs 是与百分比变化一同提供的绝对变化量。SDK 的短语方法不提供 ratingFilters 或 phraseCount，因此需要它们时，请使用 REST 调用。
5. 通过 webhook 接收每日和每周快照
配置 webhooks URL 后，review_analytics.daily_snapshot 和 review_analytics.weekly_snapshot 会在每个时段内为每个地点各触发 1 次。您可以将每个快照视为概览端点针对固定时段计算的结果：total_reviews 为 total-reviews，new_reviews_in_period 为 new-reviews，average_rating 为该时段的 overall-rating，并附带上一时段的 previous_average_rating。载荷不包含回复率、时间线和按来源细分的数据；如果您需要这些数据，请在事件到达时调用上述端点。
{ "event": "review_analytics.weekly_snapshot", "timestamp": "2026-08-24T02:00:00Z", "account_id": 11073, "location_id": "279381", "data": { "period": "2026-08-17", "granularity": "weekly", "total_reviews": 1237, "new_reviews_in_period": 18, "average_rating": 4.6123, "previous_average_rating": 4.5901 }}这组事件的数量随您的地点数量增加：400 个地点意味着每天会集中产生 400 个事件，超出您套餐每分钟上限的事件会被丢弃，不会排队。因此，快照缺失的含义并不明确。切勿将缺失的快照记录为 0；请重新读取该时段的概览。设置方法参见通过 webhook 响应事件。