Listings APIListings API
登入

檢查商家資訊狀態並取得已上線的連結

讀取地點在各發布平台的同步狀態、收集已上線的商家資訊網址、彙整涵蓋情況、檢查語音助理，並透過 webhook 接收通知，取代輪詢。

地點建立後，系統會自動向您方案中的每個發布平台提交一筆商家資訊。本指南說明如何讀取每筆商家資訊的目前狀態、取得已上線商家資訊的網址，以及在設定 webhook 後停止輪詢。

1. 取得地點的進階商家資訊

GET /locations/{locationId}/listings/premium 會針對方案中的每個進階發布平台傳回一筆記錄。它是一般陣列，不是分頁清單。對應的路由 /listings/additional 會以相同結構傳回免費目錄；沒有 listingType 查詢參數。

Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

每個資料列都會將一個 site 與機器可讀的 syncStatus 及人類可讀的 displayStatus 配對。lastUpdate 會告訴您該資料列上次變更的時間，有助於找出處理進度停滯的提交內容。

2. 讀取各發布平台的狀態

syncStatus 是用來判斷程式分支的欄位。displayStatus 是顯示給使用者的文字，而 syncIssue 則會在發布平台提供原因時包含該原因。

syncStatus意義處理方式
AVAILABLE已準備好提交，但尚未開始。無須操作。系統會自動繼續處理。
IN_PROGRESS已提交至發布平台，正在等待回應。請等待。如果已經過了數週，請檢查 lastUpdate。
PENDING_APPROVAL發布平台已收到提交內容，正在審核。請等待。
SYNCED 或 COMPLETED已上線。listingUrl 已填入值。收集連結（步驟 3）。
REQUIRING_ACTION需要您採取行動才能繼續。actionRequired 為 true。請讀取 displayStatus，然後參閱找出並修正商家資訊錯誤。
FAILED發布平台已拒絕或無法處理提交內容。請讀取 syncIssue、修正地點資料，然後再次輪詢。
CANNOT_SUBMIT此發布平台完全無法接受此地點。通常是因為發布平台不支援該國家或類別。

Google Maps 和 Facebook 會維持在 REQUIRING_ACTION，直到連結對應發布平台的帳戶：Google Maps 需要連結 Google Business Profile，Facebook 則需要連結 Facebook 粉絲專頁。這是新地點的預期狀態，並非故障。

Apple Maps 不需要連結帳戶。如果擁有者尚未連結已驗證的 Apple Business 組織帳戶，ListingsAPI 會透過自己的 Apple Business Connect 帳戶提交該地點，而 Apple 會在發布前驗證提交內容。請參閱連結 Apple Business Connect。

只有已上線的資料列才會設定 listingUrl。請篩選出 SYNCED（以及 COMPLETED），並將網址與網站名稱一起保留，以便顯示「查看已上線商家資訊」清單，或將其儲存至您自己的對應記錄中。

Live links
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

SYNCED 資料列確實可能出現 null listingUrl：有些目錄不會提供公開頁面的網址。請以狀態為準，將連結視為選用資訊。

4. 建立涵蓋情況摘要

依 syncStatus 統計資料列數量，即可為每個地點得出一個簡短的健康指標：有多少發布平台已上線、多少仍在處理中，以及多少遭到阻擋。這就是適合放在儀表板上的數字。

Coverage
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

若要針對多個地點執行此操作，請分頁讀取 GET /locations，並針對每個地點呼叫一次進階商家資訊端點。每次呼叫都會計入您的速率限制，因此請在呼叫之間留出間隔，並在收到 429 時遵循 Retry-After。找出並修正商家資訊錯誤 示範如何使用此迴圈掃描單一帳戶中的所有地點。

5. 檢查語音助理

語音助理（Google Assistant、Alexa、Siri、Cortana、Bixby）有專用的端點 GET /locations/{locationId}/voice-assistants，其狀態種類較少。Google Assistant 仰賴 Google 連線，因此未建立此連線的地點在這裡也需要處理。Siri 的結果來自該地點的 Apple Maps 商家資訊。

Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}
syncStatus意義
NOT_SUBMITTED尚未傳送至語音助理。
IN_PROGRESS正在提交。
REQUIRING_ACTION等待您處理才能繼續；請閱讀 syncIssue。
LIVE已發布。

語音助理沒有已上線頁面的連結；LIVE 就是最終狀態。

6. 接收 webhook 事件以取代輪詢

如果您已在 /dashboard/webhooks 設定 webhook URL，每當某個地點向發布平台提交的作業達到終止狀態時，就會觸發 listing.submission 事件。此事件包含 status（success、incomplete 或 canceled）和網站，並在成功時包含 live_link，也就是您在步驟 3 收集的 URL。

Route listing.submission
import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

請在 5 秒內回傳 200，之後再執行工作；系統不會重試。如需接收器的基本架構與簽章檢查方式，請參閱使用 webhook 回應事件。

後續步驟