/api/v4/locations/{locationId}/listings/premium取得地點的進階商家資訊
傳回地點方案中每個發布平台目錄的同步狀態。
參數
路徑
| 名稱 | 類型 | 必填 | 說明 |
|---|---|---|---|
| locationId | string | 必填 | Location to read. Accepts a base64-encoded Relay ID (e.g. `TG9jYXRpb246MTgwMDI4OQ==`) or a raw numeric location ID. |
回應
200Array of listings with per-directory sync status.
{ "data": { "listingsForLocation": [ { "id": "TGlzdGluZzoxMDQ0Njg3MjM=", "databaseId": "104468723", "site": { "id": "U2l0ZTox", "databaseId": "1", "name": "Google Maps", "url": "maps.google.com", "syScore": "100" }, "syncStatus": "REQUIRING_ACTION", "displayStatus": "Connect your account to sync the listing", "actionRequired": true, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:28Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MTQ=", "databaseId": "104468714", "site": { "id": "U2l0ZToxODA=", "databaseId": "180", "name": "Bing", "url": "www.bing.com", "syScore": "97" }, "syncStatus": "IN_PROGRESS", "displayStatus": "Information submitted to partner; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:35Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3Mjc=", "databaseId": "104468727", "site": { "id": "U2l0ZTozODc=", "databaseId": "387", "name": "BeLocalFocussed", "url": "belocalfocussed.com", "syScore": "80" }, "syncStatus": "SYNCED", "displayStatus": "Synced", "actionRequired": false, "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e", "connectedAccountId": null, "lastUpdate": "2026-07-06T18:33:30Z", "indexStatus": false, "syncIssue": null, "verified": false }, { "id": "TGlzdGluZzoxMDQ0Njg3MDk=", "databaseId": "104468709", "site": { "id": "U2l0ZTozMDE=", "databaseId": "301", "name": "Local Mint", "url": "localmint.com", "syScore": "69" }, "syncStatus": "FAILED", "displayStatus": "Partner experiencing issues; awaiting response", "actionRequired": false, "listingUrl": null, "connectedAccountId": null, "lastUpdate": "2026-07-06T18:34:03Z", "indexStatus": false, "syncIssue": "Publisher requires website URL", "verified": false } ] }}401Unauthenticated, missing or invalid API key.
429Rate limit exceeded. Retry after the `Retry-After` header value.
傳回地點方案所包含的每個發布平台目錄的同步狀態。每筆記錄都將 site（目錄中繼資料）與 syncStatus 及便於人員閱讀的 displayStatus 配對。上述範例節錄自 Jenny Home 的實際回應（其中傳回超過 30 個目錄），每種常見狀態各顯示一筆記錄。
商家資訊層級是路徑的一部分：/listings/premium 傳回方案中的進階目錄（如此處所示），而 /listings/additional 傳回額外／免費商家資訊。沒有 listingType 查詢參數；透過該參數傳送的值會被忽略。
使用案例：商家資訊健康狀態儀表板
擷取地點的進階商家資訊，並依 syncStatus 分組，讓您一眼掌握涵蓋情況，以及已上線、處理中或受阻的目錄數量。為 SYNCED 資料列顯示 listingUrl，讓使用者可以點選前往已上線的商家資訊，並針對任何尚未同步的項目讀取 displayStatus／syncIssue（例如 Publisher requires website URL）。
使用案例：顯示需要「連結您的帳戶」才能排除的阻礙
篩選出 actionRequired: true，以建立擁有者的待辦事項清單。在實際資料中，Google Maps、Facebook 和 Waze 傳回的狀態為 REQUIRING_ACTION，並附帶 displayStatus: "Connect your account to sync the listing"，這些發布平台需要先建立 OAuth 連線才能同步。引導擁有者前往對應的連結流程，然後再次輪詢此端點，以觀察狀態的進展。
syncStatus 的值： AVAILABLE（已準備好同步，尚未開始）、IN_PROGRESS（已提交至合作夥伴，等待回應）、PENDING_APPROVAL（等待合作夥伴核准）、SYNCED／COMPLETED（已上線；listingUrl 已填入）、REQUIRING_ACTION（需要擁有者採取行動，請參閱 displayStatus）、FAILED（同步失敗；請參閱 syncIssue）、CANNOT_SUBMIT（無法提交）。
這是以個別地點為範圍的清單，受帳戶的速率限制約束；收到 429 時，請依 Retry-After 標頭指定的等待時間重試，而非立即再次輪詢。
curl -X GET 'https://listingsapi.com/api/v4/locations/<locationId>/listings/premium' \ -H "Authorization: API $LISTINGSAPI_KEY"