衡量評論成效
讀取地點的評論 KPI、繪製每日時間軸、比較來源、找出常見詞句，並透過 webhook 接收每日與每週快照。
三個同類端點以數字描述地點的評論：KPI 總覽、每日時間軸，以及依來源細分的資料。第四個端點則列出顧客反覆使用的詞句。這些資料足以製作評分卡區塊、趨勢圖與客訴面板。
1. 讀取地點的 KPI
GET /locations/{locationId}/review-analytics-overview 會在 data.interactionsAnalyticsStats.stats 傳回四項統計資料。此處的日期範圍為選填；它會縮小計算數值與變化量所涵蓋的時間範圍。
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，因此請勿將第一個月的變化量解讀為成長。
2. 取得每日時間軸以繪製圖表
GET .../review-analytics-timeline 會在 data.interactionsChartData.data 傳回每天一筆的資料。請務必傳入 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 為每個評論來源傳回一筆資料。您可以用它查看是哪個平台使平均值產生變化。
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 傳回單純的陣列，每個重複出現的詞句各有一筆資料，其統計資料結構與總覽相同，但僅根據包含該詞句的評論計算。加入 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 接收每日與每週快照
設定 webhook URL 後，review_analytics.daily_snapshot 與 review_analytics.weekly_snapshot 會在每個期間為每個地點各觸發一次。您可以將每個快照視為總覽端點針對固定期間計算的結果：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 回應事件。