Listings APIListings API
登入

商家資訊

每個商家資訊端點皆附有 cURL、Python 和 Node 範例：進階發布平台的同步狀態、語音助理、各地點及各帳戶的重複商家資訊偵測，以及重複商家資訊移除。

商家資訊是單一地點在單一發布平台目錄中的項目。建立地點時，系統會為您方案中的每個發布平台將一筆商家資訊加入佇列，而商家資訊端點可讀取每筆商家資訊的目前狀態、列出偵測到的重複商家資訊，並確認或排除這些項目。四個 GET 端點可使用 Read（讀取）金鑰；兩個 POST 端點則需要 Write（寫入）金鑰。

端點一覽

方法路徑功能參考文件
GET/locations/{locationId}/listings/premium地點在每個進階發布平台上的同步狀態。取得進階商家資訊
GET/locations/{locationId}/voice-assistants在 Google Assistant、Alexa、Siri、Cortana、Bixby 上的同步狀態。取得語音助理商家資訊
GET/locations/listings/duplicates整個帳戶內偵測到的重複商家資訊分頁彙總。取得帳戶的所有重複商家資訊
GET/locations/{locationId}/listings/duplicates單一地點的重複商家資訊，依網站分組。取得地點的重複商家資訊
POST/locations/listings/mark-as-duplicate將商家資訊項目確認為重複項目，以便移除。將商家資訊標記為重複項目
POST/locations/listings/mark-as-not-duplicate將商家資訊項目判定為誤判並予以排除。將商家資訊標記為非重複項目

讀取進階商家資訊狀態

GET /locations/{locationId}/listings/premium

在 data.listingsForLocation 下，為地點方案中的每個進階發布平台回傳一筆記錄。這是一般陣列，不是分頁清單。同層路徑 /listings/additional 會以相同結構回傳免費目錄；此處沒有 listingType 查詢參數，傳入該參數的值會被忽略。

參數

名稱所在位置必填備註
locationIdpath是Base64 id 或數字形式的 databaseId。
Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "id": "TGlzdGluZzoxMDQ0Njg3MjM=",        "site": { "databaseId": "1", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3Mjc=",        "site": { "databaseId": "387", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3MDk=",        "site": { "databaseId": "301", "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "listingUrl": null,        "syncIssue": "Publisher requires website URL",        "lastUpdate": "2026-07-06T18:34:03Z"      }    ]  }}

請根據 syncStatus 進行分支處理。向使用者顯示 displayStatus、讀取 syncIssue 以瞭解發布平台提供的原因，並使用 lastUpdate 找出停滯的提交項目。只有已上線的資料列才會設定 listingUrl。

syncStatus意義
AVAILABLE已準備好同步，尚未開始。
IN_PROGRESS已提交至發布平台，正在等待回應。
PENDING_APPROVAL發布平台正在審核。
SYNCED 或 COMPLETED已上線。listingUrl 已填入值。
REQUIRING_ACTION需要您處理才能繼續。actionRequired 為 true；請讀取 displayStatus。
FAILED同步失敗。請讀取 syncIssue。
CANNOT_SUBMIT此發布平台完全無法接受此地點。

在連結對應帳戶之前，Google Maps、Facebook 和 Waze 會維持在 REQUIRING_ACTION，並帶有 displayStatus: "Connect your account to sync the listing"。對新地點而言，這是預期行為。

讀取語音助理狀態

GET /locations/{locationId}/voice-assistants

在 data.voiceAssistantsForLocation 下，為每個語音助理回傳一筆記錄：Google Assistant、Amazon Alexa、Apple Siri、Microsoft Cortana 和 Samsung Bixby。這是一般陣列，其狀態種類比進階商家資訊端點少。

參數

名稱所在位置必填備註
locationIdpath是Base64 id 或數字形式的 databaseId。
Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "databaseId": "104468723",        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "connectedAccountId": null,        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "databaseId": "104468711",        "voiceIdentifier": "SIRI",        "name": "Siri",        "connectedAccountId": null,        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}

請標記所有 actionRequired 為 true 或已設定 syncIssue 的資料列。errors 包含發布平台端的錯誤字串，而在適用時，connectedAccountId 會指出用於執行同步的已連結帳戶。Google Assistant 的結果來自 Google Business Profile 連線，因此未連結 Google 帳戶是其需要處理的最常見原因。Siri 的結果來自該地點在 Apple Maps 上的商家資訊。

syncStatus意義
NOT_SUBMITTED尚未傳送至語音助理。
IN_PROGRESS正在提交。
REQUIRING_ACTION需要客戶提供資訊後，同步才能繼續。
LIVE已發布。語音助理沒有已上線商家資訊的連結。

彙總帳戶內的重複商家資訊

GET /locations/listings/duplicates

在 data.duplicateListingsRollup 下傳回此金鑰可查看的所有已偵測重複商家資訊，涵蓋帳戶內的所有地點與發布平台。此端點採用位移式分頁：輸入 page 和 perPage，輸出 records[] 以及 pageInfo.totalRecords、pageInfo.totalPages 和 pageInfo.hasNextPage。篩選條件是平面查詢參數，而非 JSON。未提供任何參數時，status 預設為 POTENTIAL，tag 預設為 all，因此不帶參數的呼叫會傳回帳戶內尚未處理的重複商家資訊。

參數

名稱參數位置必填備註
statusquery否POTENTIAL（預設值）、PROCESSING、FIXED 或 FAILED。不區分大小寫。任何其他值都會產生 400。
siteIdquery否依發布平台的數字 site id（進階商家資訊端點中的 site.databaseId，或 plan-sites id），將範圍縮小至單一發布平台。
tagquery否將彙總範圍限定為單一標籤。預設為 all。
pagequery否從 1 開始的頁碼。預設為 1。
perPagequery否每頁記錄數。

Python 和 Node 包裝函式僅提供 tag 和 page。若要依 status 或 siteId 篩選，或設定 perPage，請依照處理重複商家資訊中的示範，直接呼叫路由。

Account rollup
curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "duplicateListingsRollup": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "totalPages": 34,        "totalRecords": 1673      },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "nameValid": false,          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

彙總結果會告訴您重複商家資訊位於何處：每筆記錄都會列出 locationId 和 siteName。duplicateProcessingState 與個別地點端點以 status 回報的生命週期狀態相同。請一次讀取一頁，直到 hasNextPage 為 false；以緊密迴圈連續呼叫最容易觸發 429。

狀態意義
POTENTIAL已偵測到，尚無人採取行動。
PROCESSING已確認為重複商家資訊；發布平台正在處理移除作業。
FIXED發布平台已將其移除或合併。
FAILED移除作業未成功。請檢查 liveLink。

列出單一地點的重複商家資訊

GET /locations/{locationId}/listings/duplicates

在 data.duplicateListingsForLocation 下傳回單一地點的所有已偵測重複商家資訊，並依發布平台網站分組。結果為一般陣列。每個群組代表一個網站（name、url），包含一個 listings 陣列，而每個項目都帶有兩個標記端點皆接受的 listingItemId。空陣列表示未偵測到任何重複商家資訊。

參數

名稱參數位置必填備註
locationIdpath是Base64 id 或數字 databaseId。
Duplicates for a location
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/duplicates \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

開啟 liveLink 以檢視該項目，然後保留 listingItemId。在 Node SDK 中，應傳入的值是扁平化後的 d.id。status 使用的四個值與上述帳戶彙總相同。

將商家資訊項目確認為重複

POST /locations/listings/mark-as-duplicate

將商家資訊項目標記為已確認重複，以便由發布平台移除。請在 input 下傳送 listingItemId 值，並將同一地點的所有已確認項目合併為一次批次呼叫，而非每個項目各呼叫一次。這是寫入操作，需要 Write（寫入）金鑰。

參數

名稱參數位置必填備註
input.listingItemIdsbody是來自重複商家資訊端點的 base64 listingItemId 值陣列。
input.locationIdbody否Base64 或數字地點 id。將操作範圍限定為單一地點。
Mark as duplicate
curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'
JSON
{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true 表示項目已被接受，並轉為 PROCESSING。帶有 success: false 的 200，或 400，都會附帶一個 errors 陣列，其中各項目包含 code、message 和 path；常見原因是 id 未知或格式錯誤。Python SDK 會傳回承載資料；Node SDK 則會拋出 ValidationError，因此 promise 成功解析就表示操作成功。

將商家資訊項目排除為非重複

POST /locations/listings/mark-as-not-duplicate

將疑似重複商家資訊判定為誤判並予以排除。偵測機制採取保守判定，會標記同一加盟體系的其他分店、第二個合法商家檔案，或已更名的地點。排除後，這些項目就不再出現在兩個重複商家資訊端點的結果中。此端點接受的主體與上述端點完全相同，也可用來撤銷誤標的項目。

參數

名稱參數位置必填備註
input.listingItemIdsbody是要排除的 base64 listingItemId 值陣列。
input.locationIdbody否Base64 或數字地點 id。將操作範圍限定為單一地點。
Mark as not duplicate
curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'
JSON
{  "data": {    "markAsNotDuplicate": {      "success": true,      "errors": null    }  }}

回應為 data.markAsNotDuplicate，並包含與標記為重複的呼叫相同的 success 和 errors 欄位。已排除的項目會記錄為已確認非重複，且不會在下一輪偵測時再次出現。

您會遇到的錯誤

代碼或狀態意義修正方式
401API 金鑰遺失或無效。傳送 Authorization: API $LISTINGSAPI_KEY。
帳戶彙總傳回 400status 不是 POTENTIAL、PROCESSING、FIXED、FAILED 其中之一。請使用這四個值的其中之一。
標記端點傳回 400商家資訊項目 id 不明或格式錯誤。請閱讀 errors[].code 和 message。傳送來自重複商家資訊端點的 listingItemId 值。
200，並帶有 success: false請求已執行，但輸入遭到拒絕。詳細資訊位於 data.<op>.errors。請檢查每次寫入的回應主體，而不只是狀態。
SY90016（HTTP 400）寫入時使用了 Read 金鑰。請對這兩個標記端點使用 Write 金鑰。
429已超過速率限制。Launch 方案允許每分鐘 10 次請求。等待 Retry-After 後再繼續。請參閱 速率限制。

所有代碼都列於 錯誤參考文件。

後續步驟