Listings APIListings API
登入
POST/api/v4/connected-accounts/connected-account-listings

擷取已連結帳戶的商家資訊

傳回已連結帳戶可存取的 Google Business Profile 或 Facebook 商家資訊，並提供選用的篩選與分頁功能。

需要 API 金鑰。標頭格式與金鑰輪替請參閱驗證。

參數

請求主體

名稱類型必填說明
connectedAccountIdstring必填UUID of the connected account whose listings to fetch. Send this in the JSON body: as a query parameter it is ignored.
pageinteger選填Page number to fetch. Defaults to 1.
perPageinteger選填Records per page. Defaults to 500, which is also the maximum.
locationInfostring選填Free-text search within the account's listings. Matches business name, address lines, locality, postal code, store code, and phone.

請求範例

可直接貼上的請求主體。請將預留位置 ID 與值換成您自己的。

Request body
{  "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",  "perPage": 50}

回應

200List of listings accessible to the account, with pagination metadata.
Response
{  "data": {    "connectedAccountListings": {      "pageInfo": {        "hasNextPage": false,        "hasPreviousPage": false,        "totalPages": 1,        "totalRecords": 60      },      "records": [        {          "accountTypeName": "Google",          "address": "123 William St, NY 10038, Manhattan, US",          "id": "R21iQnVsa0RhdGFMYWtlOjA2MDQ4NmExLTA0NzQtNDc4NS1iMjNhLTBkOGM4MzhmNGQ5OA==",          "liveLink": null,          "locationName": "Trial",          "phone": "(718) 667-7787"        }      ]    }  }}
401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.

傳回已連結帳戶有權存取的 Google Business Profile 或 Facebook 商家資訊。每筆記錄都包含商家資訊的 id（base64 ID）、locationName、address、phone 和 liveLink。雖然使用 POST，這仍是讀取操作，但帳戶與分頁選項必須在 JSON 主體中傳送。

使用案例：建立商家資訊選擇器。 客戶連結擁有數十筆商家資訊的 Google 帳戶後，呼叫此端點以顯示可搜尋的清單。將客戶輸入的搜尋詞放入 locationInfo（會在名稱、地址、電話、郵遞區號和商店代碼中比對），讓客戶能快速找到正確的店面。

使用案例：提供資料給 connect-listing。 每筆記錄中的 id 正是 connect-listing 預期的 connectedAccountListingId。擷取商家資訊，讓客戶（或您的比對邏輯）選擇其中一筆，再將其 id 與目標 Listings API locationId 傳給 connect-listing，以建立兩者之間的連結。

使用主體中的扁平 page 和 perPage 鍵分頁；perPage 預設為 500，這也是上限。從回應中讀取 pageInfo.hasNextPage 和 pageInfo.totalPages，以逐頁取得完整資料集。此端點的呼叫會計入帳戶的速率限制，429 會包含 Retry-After 標頭。

上述請求格式已透過實際運作的 API 驗證。範例回應僅供示意。

Request
curl -X POST 'https://listingsapi.com/api/v4/connected-accounts/connected-account-listings' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "perPage": 50  }'
Run in playground