取得彙總互動 | 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）。