擷取單一地點或您整個帳戶的評論
列出地點的最新評論、篩選出未回覆的低評分評論、使用游標分頁、掃描整個帳戶，並透過 webhook 接收通知。
評論在 API 中稱為 interactions。來自 Google、Facebook 或 Yelp 的所有評論會按地點各自彙整為一份清單傳回，並提供整個帳戶的彙總清單，因此只需一次整合，就能涵蓋您連結的所有來源。
1. 列出單一地點的最新評論
GET /locations/{locationId}/reviews 是位於 data.interactions 的游標連線。結果依時間由新到舊排序，且 first 預設為 20，因此單次呼叫並不代表完整的歷史紀錄。路徑接受 base64 id 或純數字。
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=10" \-H "Authorization: API $LISTINGSAPI_KEY"{ "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", "responded": false, "responseCount": 0, "canRespond": true, "permalink": "https://maps.google.com/maps?cid=..." }, "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..." } ], "totalCount": 425 } }}讀取 data.interactions.edges[].node。id 是一般的 UUID，而非 base64 Relay id，也是您回覆時要傳入的值。totalCount 是整個結果集中符合條件的筆數，而非本頁的筆數。canRespond 表示該來源是否接受透過 API 發出的商家回覆。
2. 篩選出未回覆的低評分評論
陣列篩選條件以 JSON 字串的形式放在查詢字串中：ratingFilters=[1,2] 保留 1 星和 2 星評論，而 responseStatus=["PENDING"] 保留沒有商家回覆的評論。括號和引號必須經過 URL 編碼，因此 cURL 範例搭配使用 -G 與 --data-urlencode，為您編碼每個值並將其附加至 URL。等效的查詢字串原文為 ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5D。
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=50'您可以組合使用的篩選條件：
3. 使用游標逐頁讀取
將 pageInfo.endCursor 作為 after 傳入。當 hasNextPage 為 false，或某一頁傳回空的 edges 陣列時，就停止讀取；如果分頁邊界剛好落在最舊的評論上，下一頁會是空白頁。兩個 SDK 都能為您逐頁讀取。
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=50&after=SW50ZXJhY3Rpb246MV8xNTU0..." \-H "Authorization: API $LISTINGSAPI_KEY"每個請求都會計入您的速率限制，而有 425 則評論的地點在 first=50 的設定下需要 9 次呼叫。收到 429 時，請依 Retry-After 等待後再讀取下一頁。執行排程同步時，請使用 startDate 和 endDate 限定本次執行的範圍，避免重新讀取歷史紀錄。請參閱速率限制。
4. 使用彙總清單掃描整個帳戶
GET /rollup_interactions 會在 data.rollupInteractions 傳回金鑰可存取的所有地點中相同的節點資料，每個節點都帶有 locationId。它接受相同的篩選條件，另加 tag，其預設值為 all。沒有地點篩選條件；請自行依 locationId 分組。目前兩個 SDK 都尚未封裝此端點，因此 SDK 範例使用 requests 和 fetch 呼叫它。
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'每個節點的結構都與步驟 1 相同，並多了一個數值型的 locationId，也就是商店的 databaseId。彙總清單的 pageInfo 可能省略 endCursor，因此請將最後一個 edge 的 cursor 作為 after；這兩個值等效。
5. 依 id 擷取完整詳細資料
如果您已儲存 id，GET /reviewDetails 就能傳回最新的資料副本，無須分頁。interactionIds 是 JSON 陣列，與其他篩選條件一樣需要經過 URL 編碼。回應在 data.interactionDetails.interactions 中提供一般陣列，且每個 interaction 都包含其 responses。
curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'{ "data": { "interactionDetails": { "interactions": [ { "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841", "responded": true, "responseCount": 1, "responses": [ { "id": "2090753a-ece6-4837-8336-8494ad308523", "content": "Thank you so much for the kind words!", "interactionStatus": "CONFIRMED" } ] } ] } }}使用另一個帳戶的 id 時，會傳回 200，其中包含 interactionDetails: null 和 SY90001 錯誤，因此請先檢查 null，再以索引存取。
6. 接收 webhook 事件，取代輪詢
設定 webhook URL 後，系統擷取評論或評論發生變更時，就會觸發 interaction.review 事件。評論欄位位於 data.interaction 之下，而非直接位於 data 之下，且 data.interaction.id 與清單傳回的 UUID 相同。
有兩點需要注意。此事件中的 location_id 會未經正規化直接傳遞：其值可能是數字字串或 null，因此請您自行轉換，不要直接採信其型別。此外，每當評論變更時，都會再次收到相同的 id，因此請將事件視為重新讀取評論的訊號，而非一次性的新增操作。傳送僅嘗試一次，不會重試，因此請保留步驟 4 的定期掃描作為備援。設定方式請參閱使用 webhook 回應事件。