輔助 API

每個輔助 API 端點都附有 cURL、Python 和 Node 範例：支援的國家與州、子類別目錄，以及您的方案涵蓋的發布平台網站。

輔助端點提供三份參考目錄，供 API 的其他部分用來驗證：支援哪些國家與州、有哪些商家類別，以及您的方案涵蓋哪些發布平台目錄。這三個端點都僅供讀取、不分頁，且會傳回完整資料集，因此使用 Read（讀取）金鑰即可，而快取比處理分頁更重要。

端點一覽

列出支援的國家與州

GET /countries

在 data.supportedCountries 下傳回完整目錄。每個國家都包含 ISO 代碼、base64 格式的 id、數字形式的 databaseId、各項目皆有各自 ISO 代碼的 states 陣列，以及三個地址旗標：hasCity（城市為必填）、stateRequired（州為必填，且會依 states 驗證）和 hasPostalCode（該國家使用郵遞區號）。未細分行政區的國家會傳回空的 states 陣列。

參數

此端點不接受任何參數。它一律傳回完整資料集。

curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "hasCity": true,        "id": "Q291bnRyeToxMw==",        "iso": "AU",        "name": "Australia",        "states": [          { "countryId": 13, "id": "139", "iso": "VIC", "name": "Victoria" },          { "countryId": 13, "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "hasCity": true,        "id": "Q291bnRyeToxNw==",        "iso": "BE",        "name": "Belgium",        "states": []      }    ]  }}

這兩個 iso 欄位就是您需要的值。建立和更新時，國家的 iso 會作為 countryIso，州的 iso 則會作為 stateIso。寫入前先依這份清單驗證這兩個值，就能將伺服器端的 400 轉為您自己表單中的明確訊息。

列出子類別

GET /sub-categories

在 data.subcategories 下以單一、不分頁的陣列傳回約 6,000 筆類別記錄。這份查詢目錄可將您以自由文字表達的商家類型轉換為寫入地點時所需的數字 id。

參數

無。每次呼叫都會傳回整份目錄。

curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "subcategories": [      {        "databaseId": 4589,        "id": "U3ViQ2F0ZWdvcnk6NDU4OQ==",        "key": "3d-printing-service",        "name": "3D printing service",        "primary": true      }    ]  }}

每筆記錄包含五個欄位，要用哪個欄位取決於用途。

每個地點可在 subCategoryId 中指定一個主要類別，並在 additionalCategoryIds 中指定最多 9 個其他類別。

列出方案網站

GET /plan-sites

在 data.planSites 下傳回您帳戶方案包含的所有發布平台目錄。這是數字網站 id 的權威清單，只有出現在此清單中的 id 才能用於 API 的其他部分。

參數

無。回應範圍限於您帳戶的方案。

curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 184,        "name": "Facebook",        "url": "facebook.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      }    ]  }}

這兩個國家陣列回答的是不同問題。supportedCountries 表示網站接受哪些國家的商家資訊，因此請先依地點的 countryIso 篩選，再提供發布平台選項。hideAddressSupportedCountries 表示網站在哪些國家會遵循隱藏地址的設定，這正是服務區域商家所需的功能。這兩個陣列都可能包含 50 個以上的代碼；上方範例已經過刪減。

網站 id 固定不變，值得熟記：1 是 Google Maps，184 是 Facebook，大多數連線流程都是針對這兩個發布平台。

地點操作連結

地點操作連結沒有獨立的端點。地點操作連結是 Google 上的按鈕，例如線上訂購、預訂餐桌和預約服務，平台會將這些連結作為地點的欄位管理，而非獨立資源。您可以在建立和更新時透過 placeActionLinks 陣列設定這些連結，並透過任何地點讀取端點讀取。

每個項目都需要 placeActionType 和 uri，可選擇設定 isPreferred 旗標，每種類型最多只能有一個首選連結，並可在更新時將 action 設為 add 或 delete。有效類型、刪除規則和同步行為都列於地點操作連結。

您會遇到的錯誤

這些端點都不會寫入資料，因此使用 Read 金鑰呼叫這些端點時，絕不會傳回 SY90016。完整清單請參閱錯誤代碼。

後續步驟

• 查詢國家和類別：以任務為導向的版本，逐步說明如何銜接至建立地點的流程。
• 新增地點：說明何處會使用 countryIso 和 subCategoryId。
• 找出並修正商家資訊錯誤：使用方案網站清單區分缺少的發布平台與發生錯誤的發布平台。
• 如需全部三個端點的完整欄位清單，請參閱支援 API 參考文件。