列出地點的互動 | 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 字串傳入。