获取汇总互动 | Listings API

参数

查询

名称	类型	必填	描述	默认值
tag	string	可选	Location tag to scope the rollup to. Defaults to `all`, every location the key can see. Omit it unless you tag locations.	all
siteUrls	string	可选	JSON-encoded array of publisher hostnames to include.	—
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. 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 rollup of interactions across the account. `data.rollupInteractions` holds the connection.

Response

{  "data": {    "rollupInteractions": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false      },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "authorName": "Priya S.",            "rating": 5,            "date": "2026-06-30T12:04:11+00:00",            "category": "Review",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

401Unauthenticated, missing or invalid API key.

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

返回账户内跨地点的互动视图。它支持与单个地点的列出互动端点相同的游标分页方式（first、last、after、before）和筛选条件。连接位于 data.rollupInteractions，每个 node 都包含一个 locationId，以便您将互动归属于对应的门店。

totalCount 是范围内所有地点中符合您筛选条件的互动总数，而不是本页返回的互动数量。省略 first 时会返回 20 条记录，因此单次调用绝不会返回完整的账户历史记录，请使用 after 逐页获取，直到您获得 totalCount 条记录。

注意：汇总范围始终涵盖整个账户

此端点没有用于指定单个地点的参数：使用默认的 tag=all 时，它会汇总 API 密钥可访问的所有地点，唯一更小的范围是地点 tag。此端点没有 locationFilters 或 locationIds 参数，传入其中任意一个都会被忽略，而不会被拒绝。请使用现有的筛选条件（siteUrls、responseStatus、sortOrder、startDate/endDate、searchString）缩小结果集，或根据每个节点的 locationId 自行对结果分组。

使用场景：账户范围内的“待回复”队列

要列出所有地点中仍在等待商家回复的全部评价，请调用 GET /rollup_interactions?responseStatus=["PENDING"]&sortOrder=["NEWEST_FIRST"]&first=50，然后使用 after = pageInfo.endCursor（等同于最后一个 edge 的 cursor）逐页获取，直到 hasNextPage 为 false，或某一页返回空的 edges 数组时停止。这样可以避免逐个地点遍历。由于此端点采用分页并设有速率限制，请在收到 429 时遵循 Retry-After 响应头的要求，并在定时同步时优先使用限定日期范围的调用（startDate/endDate）。