取得地點的貼文 | Listings API

參數

路徑

名稱	類型	必填	說明
locationId	string	必填	Base64-encoded location cursor / global ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`). Pass it unchanged, do not URL-encode it. The base64 cursor always resolves; the raw numeric database ID also works on this endpoint, but the base64 form is the portable choice across the API.

查詢

名稱	類型	必填	說明	預設值
page	integer	選填	1-based page number for offset pagination.	1
perPage	integer	選填	Number of records per page. Must not exceed 50.	10

回應

200A page of post campaigns for the location, under `data.postsByLocation`. `records` is empty when the location has no posts yet.

Response

{  "data": {    "postsByLocation": {      "records": [        {          "id": "U29jaWFsUG9zdDo0NDEyMg==",          "name": "Summer Hours Update",          "status": "SUCCESS",          "type": "ANNOUNCEMENT",          "createdAt": "2026-06-28",          "scheduledStartDate": "2026-06-28",          "scheduledEndDate": "2026-07-28",          "views": 128,          "clicks": 14,          "shares": 0,          "reactions": 3,          "comments": 1,          "sites": ["GOOGLE"],          "message": [            { "site": "GOOGLE", "message": "We have extended our summer hours! Open until 9pm on weekdays." }          ],          "cta": [            { "type": { "value": "LEARN_MORE", "label": "Learn more" }, "url": "https://jennyhome.example/hours", "site": "GOOGLE", "tinyUrl": "https://tiny.cc/jh-hours" }          ],          "contextInfo": null,          "mediaUrl": [            { "url": "https://cdn.listingsapi.com/posts/44122/summer.jpg", "site": "GOOGLE", "type": "IMAGE" }          ],          "publishDetails": [            { "site": "GOOGLE", "status": "PUBLISHED", "createdDate": "2026-06-28", "publishedDate": "2026-06-28", "submissionError": null }          ],          "postLinks": [            { "site": "GOOGLE", "link": "https://www.google.com/maps/place/?post=44122" }          ],          "locationIds": [1800289],          "clientName": "Jenny Home"        }      ],      "locationDetails": [        {          "id": "TG9jYXRpb246MTgwMDI4OQ==",          "name": "Jenny Home",          "street": "600 Congress Ave, Suite 200",          "city": "Austin",          "postalCode": "78701",          "countryIso": "US",          "stateIso": "TX",          "stateName": "Texas",          "storeId": null        }      ],      "pageInfo": {        "totalPages": 1,        "hasNextPage": false,        "hasPreviousPage": false,        "totalRecords": 1      }    }  }}

401Unauthenticated, missing or invalid API key.

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

使用此端點可擷取單一門市的貼文歷史記錄，涵蓋包含該地點的每項公告、活動及優惠行銷活動，以及其生命週期 status 和各則貼文的互動計數（views、clicks、reactions）。

使用案例：行銷活動前稽核。為 Jenny Home 排程新的 Google 貼文之前，請呼叫 GET /locations/TG9jYXRpb246MTgwMDI4OQ==/posts，查看哪些貼文已上線、哪些貼文仍為 SCHEDULED，以及上一則公告的成效。讀取每筆記錄的 type 以找出優惠；此端點不提供伺服器端的類型篩選功能。

注意事項。

此端點僅接受 page 和 perPage 引數。這裡沒有 filters、sortFields、locationIds 或 componentIdentifier 參數（這些參數屬於 bulk-posts 端點），傳送其中任一參數時，該參數會被忽略，而不會遭到拒絕。請在您自己的程式碼中篩選及排序傳回的 records。
此路由會直接拒絕 tag，並傳回 tag is not a supported parameter for this query。若您需要根據標籤解析出一組地點，請使用 bulk-posts 端點。
perPage 的上限為 50；超過此值會失敗，並傳回 per_page must not exceed 50。
請將 locationId 作為 base64 游標（例如 TG9jYXRpb246MTgwMDI4OQ==）傳入，完全使用清單／搜尋端點傳回的原值，不要做 URL 編碼。
分頁採用位移量機制：請使用 page 和 perPage（預設為 10），並讀取 pageInfo.totalPages／pageInfo.totalRecords 以判斷何時停止。
持續輪詢可能會觸及帳戶的速率限制（HTTP 429）；請遵循 Retry-After 標頭。

上述範例中的 records 陣列僅供示意。實際環境中的範例地點（Jenny Home）目前沒有社群貼文，因此實際呼叫會傳回 records: [] 和 pageInfo.totalRecords: 0。

相關操作：使用 POST /posts 建立貼文、使用 GET /posts/{postId} 取得單一行銷活動，或使用 GET /locations/{locationId}/bulk-posts 列出大量（多地點）行銷活動；該端點則接受 filters 和 sortFields，並在 rollupSocialPosts 下傳回結果。