評論
使用 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
分析 1 個或多個地點在指定日期範圍內的詞組與情緒。接受單一選項物件；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();