列出地点的互动 | Listings API

参数

路径

名称	类型	必填	描述
locationId	string	必填	Location ID, a raw numeric database ID (e.g. `1800289`) or its Base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`).

查询

名称	类型	必填	描述	默认值
siteUrls	string	可选	JSON-encoded array of publisher hostnames to include, e.g. `["maps.google.com","yelp.com"]`.	—
startDate	string	可选	Start of the date-range filter (YYYY-MM-DD).	—
endDate	string	可选	End of the date-range filter (YYYY-MM-DD).	—
searchString	string	可选	Full-text search across interaction content.	—
category	string	可选	Single interaction category, e.g. `REVIEW`.	—
categories	string	可选	JSON-encoded array of interaction categories.	—
ratingFilters	string	可选	JSON-encoded array of star ratings to include, e.g. `[3,4]`.	—
ratingFilter	integer	可选	Single star rating to filter by.	—
responseStatus	string	可选	JSON-encoded response-status filter. Values: `RESPONDED`, `PENDING`.	—
sortOrder	string	可选	JSON-encoded sort order. Values: `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`.	—
first	integer	可选	Number of records to return from the beginning (newest first). Defaults to 20 when omitted, the endpoint always returns a single page, never the whole history.	—
after	string	可选	Cursor to page forward from. Pass `pageInfo.endCursor`, or equivalently the `cursor` of the last edge in the previous page.	—
last	integer	可选	Number of records to return from the end.	—
before	string	可选	Cursor to page backward from, used with `last`. Pass the `cursor` of the first edge of the page you are moving back from. `pageInfo` carries no `startCursor` field, so the edge cursor is the value to use.	—

响应

200Paginated interactions result. `data.interactions` holds the connection.

Response

{  "data": {    "interactions": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0MjQzMDczMDM2LTllMjZkMmE4LWE2ZWQtNDJlYS04NDU0LTQ3ZDFjOTJlYTg0MQ=="      },      "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",            "category": "Review",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0MjQzMDczMDM2LTllMjZkMmE4LWE2ZWQtNDJlYS04NDU0LTQ3ZDFjOTJlYTg0MQ=="        }      ],      "totalCount": 425    }  }}

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

使用基于游标的分页方式返回某个地点的评价和社交互动。结果默认按从新到旧的顺序排列。连接位于 data.interactions，包含 edges[].node（请参阅互动属性参考）、pageInfo 中的一个 endCursor 以及一个 totalCount。

totalCount 是整个结果集中符合您筛选条件的互动数量，而不是本页返回的数量。您可以用它来估算历史数据回填的规模，或核对您自行统计的总数：如果某地点的 totalCount: 450，以 first=50 读取需要 9 次请求，读取到末尾时，各页数量之和应为 450。省略 first 会返回 20 条记录，因此单次调用绝不会返回完整的历史记录。

使用场景：单个门店的评价收件箱

要为一个地点构建评价收件箱，请使用 first 和 after 向后翻页：请求 first=25，然后在下一次调用中将响应中的 pageInfo.endCursor 作为 after 传入。每条 edge 也带有自己的 cursor，而最后一条 edge 的 cursor 就是该页的 endCursor，因此这两个值中的任意一个都可以用作 after。当 hasNextPage 为 false 或某页返回的 edges 数组为空时停止，您需要检查这两个条件，因为如果某页恰好以最早的评价结尾，后面还会返回最后一个空页。叠加 responseStatus=["PENDING"] 可仅显示仍在等待商家回复的评价，或叠加 ratingFilters=[1,2] 以优先处理负面评价。每个 node 中的 id 就是要传给回复互动的值，canRespond 表示该来源是否接受商家回复。

使用场景：增量同步

要保持本地镜像同步，请按 startDate／endDate 筛选，使用 sortOrder=["NEWEST_FIRST"] 排序，并持久化保存您已见到的最大 date 值。请注意，此端点采用分页并有速率限制，收到 429 时请遵循 Retry-After 响应头，并避免每次运行时都重新获取完整的历史记录。

所有套餐均支持 Google Maps 和 Facebook。Growth 和 Enterprise 套餐支持 Yelp。JSON 编码的筛选条件（siteUrls、categories、ratingFilters、responseStatus、sortOrder）以经过 URL 编码的 JSON 字符串形式传递。