評論是客戶在 Google、Facebook 和 Yelp 留下的星級評分與留言。API 會儲存每則評論的一份副本，讓您回覆，並計算評論分析資料。REST 路徑使用 reviews；回應的鍵與參考頁面標題使用 interactions，這是同一物件過去的內部名稱。本指南一律使用「評論」一詞。讀取需要 Read（讀取）金鑰。回覆、編輯、封存及變更設定需要 Write（寫入）金鑰；使用 Read 金鑰執行寫入操作時，會傳回 400，並附帶 SY90016。

端點一覽

方法	路徑	功能	參考文件
`GET`	`/reviews/site-config`	帳戶方案允許使用的評論來源。	列出帳戶的評論來源
`GET`	`/locations/{locationId}/reviews/settings`	為單一地點設定的來源。	列出地點的評論來源
`POST`	`/locations/reviews/settings/edit`	設定地點的來源與正面評論門檻。	編輯評論設定
`GET`	`/locations/{locationId}/reviews`	以游標分頁列出單一地點的評論。	列出評論
`GET`	`/rollup_interactions`	以游標分頁列出所有地點的評論。	取得彙總評論
`GET`	`/reviewDetails`	依 id 取得評論的最新副本，包含回覆。	依 id 取得評論
		評論與回覆物件的欄位參考文件。	評論屬性
`POST`	`/locations/reviews/respond`	發布商家擁有者回覆。	回覆評論
`POST`	`/locations/reviews/respond/edit`	變更回覆文字。	編輯回覆
`POST`	`/locations/reviews/respond/archive`	將回覆從追蹤中移除。	封存回覆
`GET`	`/review-phrases`	客戶反覆使用的詞句及其統計資料。	列出評論詞句
`GET`	`/locations/{locationId}/review-analytics-overview`	4 項 KPI 及其期間變化量。	評論分析總覽
`GET`	`/locations/{locationId}/review-analytics-timeline`	每日評論數與平均評分。	評論分析時間軸
`GET`	`/locations/{locationId}/review-analytics-sites-stats`	各來源的評分、評論數量與近期程度。	依網站分析評論

列出您的方案允許使用的評論來源

GET /reviews/site-config 會傳回帳戶有權使用的評論平台目錄。此端點不接受參數，且作用範圍為單一帳戶，因此請快取結果，無須針對每個地點呼叫。siteUrl 的值是此資源中所有其他篩選條件接受的主機名稱。

名稱	位置	必填	備註
無			無參數。

Account sources

curl https://listingsapi.com/api/v4/reviews/site-config \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "interactionSiteConfig": [      { "site": "Google", "siteUrl": "maps.google.com" },      { "site": "Facebook", "siteUrl": "facebook.com" },      { "site": "Yelp", "siteUrl": "yelp.com" }    ]  }}

讀取 data.interactionSiteConfig[]。此範例使用 Launch 方案帳戶；確切的平台集合取決於方案與產業類別。請將 siteUrl 用於清單端點的 siteUrls 篩選條件，以及編輯設定時的 siteUrls[].name。

列出為地點設定的來源

GET /locations/{locationId}/reviews/settings 會針對方案支援的每個平台傳回一筆項目，其中包含擷取評論所用的 URL。這是下方編輯端點所對應的讀取端點。路徑接受 base64 id 或一般數字。

名稱	位置	必填	備註
`locationId`	path	是	Base64 Relay id 或數字形式的 `databaseId`。

Location sources

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews/settings \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "interactionsSetting": {      "siteSettings": [        { "name": "maps.google.com", "url": null },        { "name": "facebook.com", "url": null },        { "name": "yelp.com", "url": null }      ]    }  }}

讀取 data.interactionsSetting.siteSettings[]。url 不為 null 表示平台已連結，且正在從該頁面擷取評論。url 為 null 表示平台可用，但尚未設定。當您透過 OAuth 連結 Google 和 Facebook 帳戶時，系統會自動填入這些平台的設定，且無法透過編輯端點覆寫。Yelp 必須明確指定。

編輯地點的評論設定

POST /locations/reviews/settings/edit 會設定地點要監控的來源，以及判定為正面評論的星級評分。欄位直接放在主體中，不放在 input 包裝物件內。新增來源會將擷取作業加入佇列，因此新網站的評論會稍後匯入，不會包含在此次回應中。

名稱	位置	必填	備註
`locationId`	body	是	僅接受 Base64 Relay id。主體中的數字 id 會導致失敗，並傳回 `SY90002`。
`siteUrls`	body	否	以 `name` 和 `url` 配對表示的完整來源集合。會取代目前的選取項目。
`siteUrls[].name`	body	否	來自 `siteSettings[].name` 的網站鍵，例如 `maps.google.com` 或 `yelp.com`。
`siteUrls[].url`	body	否	該地點在此網站上的頁面。對於需要 URL 的來源，設為 `null` 或省略此欄位會停止監控。
`positiveInteractionThreshold`	body	否	評論評分達到或超過此值時，即視為正面評論。單獨傳送此欄位時，來源設定會維持不變。

Edit settings

curl -X POST https://listingsapi.com/api/v4/locations/reviews/settings/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "locationId": "TG9jYXRpb246MTgwMDI4OQ==",  "positiveInteractionThreshold": 4,  "siteUrls": [    { "name": "maps.google.com", "url": null },    { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland" }  ]}'

JSON

{  "data": {    "editInteractionsSetting": {      "errors": null,      "interactionSetting": {        "locationId": "1800289",        "positiveInteractionThreshold": 4,        "siteSettings": [          { "name": "maps.google.com", "url": null, "monitored": true, "canRespond": true },          { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland", "monitored": true, "canRespond": false }        ]      }    }  }}

讀取 data.editInteractionsSetting.interactionSetting.siteSettings[] 以取得已儲存的選取項目。monitored 表示來源已啟用；canRespond 表示是否可透過 API 在該來源發布商家擁有者回覆。未通過驗證的來源，例如無法連線的 URL 或方案未涵蓋的網站，會出現在傳回的 errors 中，且設定維持不變，因此收到 200 時，請檢查 errors。SDK 在這種情況下會拋出 ValidationError。

列出地點的評論

GET /locations/{locationId}/reviews 是位於 data.interactions 的游標連線，依時間由新到舊排序。first 預設為 20，因此單次呼叫絕不會取得完整歷史記錄。陣列篩選條件在查詢字串中以 JSON 字串表示，且必須經過 URL 編碼；cURL 範例使用 -G 搭配 --data-urlencode 來完成此編碼。

名稱	所在位置	必填	備註
`locationId`	path	是	Base64 Relay id 或數字形式的 `databaseId`。
`first`, `after`	query	否	向前分頁。將 `pageInfo.endCursor` 作為 `after` 傳入。
`last`, `before`	query	否	向後分頁。`pageInfo` 沒有 `startCursor`，因此請傳入第一個 edge 的 `cursor`。
`siteUrls`	query	否	主機名稱的 JSON 陣列，例如 `["maps.google.com"]`。
`ratingFilters`	query	否	星等評分的 JSON 陣列，例如 `[1,2]`。
`responseStatus`	query	否	JSON 陣列：`["PENDING"]` 或 `["RESPONDED"]`。
`sortOrder`	query	否	JSON 陣列：`["NEWEST_FIRST"]`、`["OLDEST_FIRST"]` 或 `["LAST_RESPONDED"]`。
`startDate`, `endDate`	query	否	`YYYY-MM-DD`，以一般字串表示。
`searchString`	query	否	對評論內文進行全文搜尋。

另可使用參考頁面列出的選填參數 category、categories，以及單值參數 ratingFilter。

List reviews

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=25'

JSON

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

讀取 edges[].node。id 是您回覆時要傳入的值，而 canRespond 表示該來源是否接受商家擁有者回覆。totalCount 是整個結果集中符合條件的項目數，而非此頁的項目數。當 hasNextPage 為 false，或某一頁傳回空的 edges 時，請停止分頁；若分頁邊界恰好落在最舊的評論上，下一頁會是空白頁。

篩選條件	值
`responseStatus`	`RESPONDED`, `PENDING`
`sortOrder`	`NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`
`category`	`REVIEW`，以及各帳戶提供的其他分類

使用彙總端點掃描所有地點

GET /rollup_interactions 是位於 data.rollupInteractions 的相同游標連線，涵蓋該金鑰可存取的所有地點，每個節點上都有數字形式的 locationId。它接受與個別地點清單相同的篩選條件。此端點沒有地點篩選條件；locationIds 引數會被忽略，而不會遭到拒絕。兩個 SDK 目前都尚未封裝此端點，因此範例使用 requests 和 fetch。

名稱	所在位置	必填	備註
`tag`	query	否	用於限定範圍的地點標籤。預設為 `all`。除非您有為地點加上標籤，否則請省略。
`first`, `after`, `last`, `before`	query	否	游標分頁，與清單端點相同。
`siteUrls`, `ratingFilters`, `responseStatus`, `sortOrder`	query	否	經過 URL 編碼的 JSON 陣列，值與清單端點相同。
`startDate`, `endDate`, `searchString`	query	否	與清單端點相同。

Account rollup

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

JSON

{  "data": {    "rollupInteractions": {      "pageInfo": { "hasNextPage": true, "hasPreviousPage": false },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "rating": 5,            "responded": false,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

依 locationId 將節點分組，此值是商店的 databaseId。彙總結果的 pageInfo 可能會省略 endCursor，因此請將最後一個 edge 的 cursor 作為 after；這兩個值等效。請使用 startDate 和 endDate 限定排程執行的範圍，避免重新讀取歷史記錄，並在收到 429 時遵循 Retry-After。

依 id 擷取評論

GET /reviewDetails 會傳回已儲存評論的最新副本，無須分頁。回應在 data.interactionDetails.interactions 中提供一般陣列，不含 edges 或 pageInfo，且每則評論都包含其 responses。使用此端點可重新載入追蹤清單中的完整資料，並找到編輯或封存所需的 responseId。

名稱	所在位置	必填	備註
`interactionIds`	query	是	經過 URL 編碼的評論 UUID JSON 陣列。省略此參數會傳回 `SY90006`。

Details by id

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0"]'

JSON

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0",          "source": "maps.google.com",          "content": "Great place for dessert!",          "rating": 5,          "responded": true,          "responseCount": 1,          "canRespond": true,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED",              "editedResponse": false            }          ]        }      ]    }  }}

responses[].id 是編輯與封存端點使用的 responseId。傳入其他帳戶的 id 時，端點會傳回 200，並附帶 interactionDetails: null 和 SY90001 錯誤，因此請先檢查 null，再以索引存取。

評論與回覆欄位

屬性參考是僅供文件說明的頁面，列出評論物件與回覆物件上的所有欄位。您最常使用的欄位如下：

欄位	型別	意義
`id`, `interactionId`	string	相同的 UUID；回覆時請將其作為 `interactionId` 傳入。
`source`	string	網站的主機名稱，例如 `maps.google.com`。
`content`, `authorName`, `rating`, `date`	mixed	內文、評論者、1 至 5 星評分、ISO 8601 時間戳記。
`type`	string	`Review`、`Question`、`Comment`、`Recommendation`、`Post`、`Photo`、`Message` 或 `Response`。
`category`	string	高階分類，`Review` 或 `Social`。
`responded`, `responseCount`, `responses`	mixed	是否有商家擁有者回覆、回覆數量，以及回覆物件。
`canRespond`	boolean	是否可透過 API 向此來源發布回覆。
`permalink`	string	來源網站上該評論的連結。
`locationId`	integer	地點的數字形式的 `databaseId`。

responses[] 中的每則回覆都包含 id、content、authorName、date、interactionStatus、editedResponse、respondedWith（範本 id）及 remarks（失敗詳細資訊）。interactionStatus 會經歷下列狀態：

狀態	意義
`CREATED`	已接受並排入佇列，等待傳送至發布平台。
`COMPLETED`	已發布至發布平台。部分平台的狀態到此為止。
`CONFIRMED`	已發布，且已獲發布平台確認。
`FAILED`	發布平台已拒絕此回覆。`remarks` 說明原因。

發布商家擁有者回覆

POST /locations/reviews/respond 會在來源平台上發布公開回覆。欄位直接放在主體中。回覆會立即被接受，並以非同步方式傳送，因此 interactionStatus 的初始值為 CREATED。請先檢查該評論的 canRespond。

名稱	所在位置	必填	備註
`interactionId`	body	是	該評論的 `id`。
`responseContent`	body	是	回覆文字。
`respondedWith`	body	否	如果回覆來自範本，則填入回覆範本的 id。

Respond

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'

JSON

{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

請保留 interaction.id：這是編輯和封存時使用的 responseId。回覆遭到拒絕時，會傳回 200，並在 data.respondToInteraction 中填入 errors，因此請讀取主體；SDK 會拋出 ValidationError。稍候片刻後，請透過 id 重新讀取該評論，確認回覆是否已達到 COMPLETED 或 CONFIRMED。

編輯回覆

POST /locations/reviews/respond/edit 會變更現有回覆的文字。編輯內容會重新提交至平台，因此 interactionStatus 會回到 CREATED，而 editedResponse 會在編輯內容成功套用後變為 true。對於僅允許一則回覆的平台，請優先使用此方式，而非封存後重新發布。

名稱	所在位置	必填	備註
`reviewId`	body	是	該評論的 `id`。
`responseId`	body	是	從 `responses[]` 取得的回覆 `id`。
`responseContent`	body	是	新的回覆文字。
`templateId`	body	否	要將回覆重新歸屬至哪個回覆範本，請填入該範本的 id。

Edit reply

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'

JSON

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

編輯請求被接受時，status 為字串 "true"。請呼叫詳細資料端點以確認新文字，並檢查回覆的 interactionStatus。

封存回覆

POST /locations/reviews/respond/archive 會將回覆從我們這端追蹤的該評論 responses 中移除。這是軟刪除：已在 Google、Yelp 或 Facebook 上公開的回覆仍會保留在該平台上。請使用此功能清除失敗或已被取代的草稿；對於已發布的回覆，請使用編輯功能。

名稱	所在位置	必填	備註
`responseId`	body	是	從 `responses[]` 取得的回覆 `id`。

Archive reply

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'

JSON

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

封存後，該評論的 responseCount 會減少，responded 則會反映剩餘的回覆。

列出顧客反覆使用的詞句

GET /review-phrases 會在 data.newReviewPhrases 傳回一般陣列，每個反覆出現的詞句各有一個項目，各項目的統計資料僅根據包含該詞句的評論計算。結果不分頁；請使用 phraseCount 限制數量。每個篩選條件皆為選填，且可組合使用，因此將 ratingFilters=[1,2] 與 startDate 搭配使用，即可取得上一季的抱怨內容。

名稱	所在位置	必填	備註
`locationIds`	query	否	由數字地點 id 組成的 JSON 陣列，例如 `[1800289]`。省略此欄位即可涵蓋該金鑰可讀取的所有地點。
`siteUrls`	query	否	由主機名稱組成的 JSON 陣列。
`startDate`, `endDate`	query	否	`YYYY-MM-DD`.
`ratingFilters`	query	否	由星級評分組成的 JSON 陣列。
`responseStatus`	query	否	由 `RESPONDED` 或 `PENDING` 組成的 JSON 陣列。
`sortOrder`	query	否	`NEWEST_FIRST`、`OLDEST_FIRST`、`LAST_RESPONDED`、`LOWEST_RATING` 或 `HIGHEST_RATING`。
`phraseCount`	query	否	傳回詞句數量的上限。
`searchString`	query	否	僅包含此子字串的詞句。

此外，還有參考頁面中列出的選填 categories，以及已棄用的單值 category 和 ratingFilter。

Phrases

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'

JSON

{  "data": {    "newReviewPhrases": [      {        "reviewPhrase": "friendly staff",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 46, "delta": 12.5, "abs": 5 },            { "name": "overall-rating", "value": 4.7, "delta": 1.1, "abs": 0.05 }          ]        }      },      {        "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 則是絕對變動量。若傳回的 403 包含 SY90003，表示該金鑰無法讀取所請求地點中的某個地點。

讀取地點的評論 KPI

GET /locations/{locationId}/review-analytics-overview 會在 data.interactionsAnalyticsStats.stats 傳回四項統計資料。日期範圍為選填；它會縮小計算數值及其變動量所使用的時間範圍。每個 delta 都是相較於前一個相同長度期間的變動百分比。

名稱	所在位置	必填	備註
`locationId`	path	是	Base64 Relay id 或數字形式的 `databaseId`。
`startDate`, `endDate`	query	否	`YYYY-MM-DD`。與時間軸不同，此處為選填。

Overview

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "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 }      ]    }  }}

`name`	`value`	解讀方式
`total-reviews`	數量	該地點的所有評論。
`new-reviews`	數量	期間內收到的評論。
`overall-rating`	1 至 5	平均星級評分。
`review-response-rate`	百分比	有商家擁有者回覆的評論占比。

沒有前一期資料的新帳戶，其 delta 會顯示為 100，因此請勿將第一個月的變動量解讀為成長。

取得每日評論時間軸

GET /locations/{locationId}/review-analytics-timeline 會在 data.interactionsChartData.data 傳回每天一筆的項目。只要圖表的日期範圍有要求，就請傳入 startDate 和 endDate；省略這些參數會讓服務自行選擇時間範圍。加入 site 即可單獨繪製某個來源的資料。

名稱	所在位置	必填	備註
`locationId`	path	是	Base64 Relay id 或數字形式的 `databaseId`。
`startDate`, `endDate`	query	否	`YYYY-MM-DD`。請同時傳入兩者，讓時間範圍可預期。
`site`	query	否	`siteSettings[].name` 中的一個主機名稱，例如 `maps.google.com`。兩個 SDK 都未提供此參數；請使用 REST 呼叫。

Timeline

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31&site=maps.google.com" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "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 繪製為折線。平均值僅代表當天，並非累計平均值，而且沒有評論的日期會是 null，因此請保留空缺，不要繪製為零。

依來源細分評論分析

GET /locations/{locationId}/review-analytics-sites-stats 會在 data.interactionsSitesStats.stats 傳回每個評論來源各一筆的項目。使用此資料找出哪個平台影響了平均值。

名稱	所在位置	必填	備註
`locationId`	path	是	Base64 Relay id 或數字形式的 `databaseId`。
`startDate`, `endDate`	query	否	`YYYY-MM-DD`。差值會將本期與長度相同的前一期進行比較。

By source

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"

JSON

{  "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",          "baseRating": 4.5,          "baseInteractions": 388,          "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；baseRating 和 baseInteractions 是計算差值所依據期間的起始值。recency 是最新評論的時間戳記；如果來源從未傳回評論，則為 null。newInteractions 為 0，且 recency 已是數個月前，通常表示來源連線已失效，因此請檢查該地點的來源。

您會遇到的錯誤

代碼	意義	修正方式
`SY90016`	使用 Read 金鑰執行寫入操作。	請使用 Write 金鑰。
`SY90001`	未獲授權：金鑰無效，或評論 id 屬於另一個帳戶。在 `/reviewDetails` 上，此錯誤會以 `200` 傳回，並附帶 `interactionDetails: null`。	請檢查金鑰和 id。
`SY90002`	id 無效。設定編輯請求的主體中使用了數字形式的 `locationId`。	請傳送 base64 Relay id。
`SY90003`	`403`，此金鑰無法讀取或變更此地點。	請使用具有該地點存取權的金鑰。
`SY90006`	`/reviewDetails` 缺少 `interactionIds`。	請傳入包含 id 的 JSON 陣列。
`SY50121`	對同一則 Google 評論新增第二則商家擁有者回覆。	請編輯現有回覆。
`429`	速率限制。	請等待 `Retry-After`。請參閱速率限制。

寫入操作也可能傳回 200，且 data.<op> 內的 errors 已填入內容，因此請讀取每次寫入操作的回應主體。完整清單請參閱錯誤代碼。

後續步驟

擷取評論：建立待處理佇列，並透過 webhook 接收通知。
回覆評論：回覆、確認、編輯、封存。
評論分析：評分卡、圖表、客訴面板、每日快照。
分析：同一地點在 Google、Facebook 和 Bing 上的商家檔案指標。
參考文件首頁：評論。SDK：Python 評論、Node 評論。