获取单个地点或您整个账户的评价
列出某个地点的最新评价，筛选未回复的低分评价，使用游标分页，遍历整个账户，并通过 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 事件，取代轮询
配置 webhooks URL 后，当评价被录入或发生变化时，会触发 interaction.review 事件。评价字段位于 data.interaction 下，而非直接位于 data 下，且 data.interaction.id 与列表返回的 UUID 相同。
有 2 点需要注意。此事件中的 location_id 会未经规范化直接传递：它可能是数字字符串或 null，因此请您自行转换，不要直接信任其类型。此外，每当评价发生变化时，都会再次收到相同的 id，因此请将此事件视为重新读取评价的信号，而非一次性插入操作。事件仅尝试投递 1 次，不会重试，因此请保留步骤 4 中的定期扫描作为兜底措施。设置方法请参阅 通过 webhook 响应事件。