Listings APIListings API
登入
GET/api/v4/countries

列出支援的國家與州

傳回 Listings API 支援的所有國家，以及各國的州／省、建立或更新地點時使用的 ISO 代碼，以及各國要求填寫或檢查的地址欄位。

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

參數

此端點不接受任何參數。

回應

200List of supported countries, each with its states and ISO codes. The live response is trimmed here to the United States, with three of its states.
Response
{  "data": {    "supportedCountries": [      {        "databaseId": 233,        "hasCity": true,        "id": "Q291bnRyeToyMzM=",        "iso": "US",        "name": "United States",        "hasPostalCode": true,        "stateRequired": true,        "states": [          { "countryId": 233, "id": "3542", "iso": "CA", "name": "California" },          { "countryId": 233, "id": "3537", "iso": "NY", "name": "New York" },          { "countryId": 233, "id": "3524", "iso": "TX", "name": "Texas" }        ]      }    ]  }}
401Unauthenticated, missing or invalid API key.
500Internal server error.

傳回 Listings API 地點資料支援的所有國家及其行政區劃（州、省、領地）的完整清單。每個國家項目都包含其 ISO 代碼（iso）、Relay id、數值型 databaseId、states 陣列，以及三個標記，用來說明該國如何檢查地點的地址。每個州都包含自己的 iso 和數值型 id。若 Listings API 未細分某個國家的行政區劃，該國便會傳回空的 states 陣列。

各國的地址規則

標記truefalse
hasCity建立時必須提供 city（SY10126）。該國的地址不使用城市層級。您傳送的 city 會被捨棄。
stateRequiredstateIso 為必填，且必須是該國的 states 之一（SY10010）。請省略 stateIso。這些國家中有些仍會列出 states；您傳送的值會被儲存，但不會經過檢查。
hasPostalCode該國使用郵遞區號。請隨地址一併傳送 postalCode。該國沒有郵遞區號系統。請省略 postalCode。

postalCode 在所有國家皆為選填，但只要 hasPostalCode 為 true，就請傳送此欄位：部分發布平台需要此欄位才能放置地圖標記。您傳送的值會依該國的格式檢查（SY10014）。若地點已設定 hideAddress: true，則會略過城市和州的檢查。

使用案例：填入地址下拉式選單的選項。 在應用程式啟動時擷取一次此資料，並將其快取。使用 name／iso 顯示國家選擇器，並在選定國家後，使用該國的 states 填入州選擇器的選項。iso 的值可直接填入 create-location 和 update-location 端點的 countryIso 與 stateIso 欄位。

使用案例：在提交前驗證地址。 呼叫 create-location 前，請確認目標 countryIso 存在於此清單中、當 stateRequired 為 true 時，stateIso 列於該國之下，以及當 hasCity 為 true 時，已設定 city。在此階段偵測到不支援的代碼，即可在用戶端顯示清楚的訊息，而不會等到建立呼叫傳回 400。完整回應的資料量很大（包含所有支援的國家）；上方範例已精簡為單一項目。此端點沒有查詢參數，一律傳回完整資料集。

Request
curl -X GET 'https://listingsapi.com/api/v4/countries' \  -H "Authorization: API $LISTINGSAPI_KEY"
Run in playground