/api/v4/countriesサポート対象の国と州の一覧を取得
Listings API がサポートするすべての国について、州・県、拠点の作成時や更新時に使用する ISO コード、各国で必須となる住所フィールドや検証対象となる住所フィールドを返します。
パラメーター
このエンドポイントにパラメーターはありません。
レスポンス
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.
{ "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 配列、およびその国で拠点の住所をどのように検証するかを示す 3 つのフラグが含まれます。各州には、固有の iso と数値の id が含まれます。Listings API で行政区分を設定していない国については、空の states 配列を返します。
国ごとの住所ルール
postalCode はすべての国で任意ですが、一部の掲載先では地図上にピンを配置するために必要となるため、hasPostalCode が true の場合は必ず送信してください。送信した値は、その国の形式に照らして検証されます(SY10014)。拠点に hideAddress: true が設定されている場合、市区町村と州の検証はスキップされます。
ユースケース:住所のドロップダウンに選択肢を設定する。 アプリの起動時にこのデータを 1 回取得し、キャッシュしてください。name/iso を使って国の選択欄を表示し、国が選択されたら、その国の states を使って州の選択欄に選択肢を設定してください。iso の値は、create-location エンドポイントと update-location エンドポイントの countryIso フィールドと stateIso フィールドにそのまま使用できます。
ユースケース:送信前に住所を検証する。 create-location を呼び出す前に、対象の countryIso がこの一覧に存在すること、stateRequired が true の場合は stateIso がその国の配下に記載されていること、hasCity が true の場合は city が設定されていることを確認してください。この段階でサポート対象外のコードを検出すると、作成の呼び出しで 400 が返される代わりに、クライアント側で明確なメッセージを表示できます。完全なレスポンスはサポート対象のすべての国を含むため大きくなり、上記の例では 1 件のエントリのみを示しています。クエリパラメーターはなく、このエンドポイントは常に全件を返します。
curl -X GET 'https://listingsapi.com/api/v4/countries' \ -H "Authorization: API $LISTINGSAPI_KEY"