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 数组，以及 3 个标志，用于说明如何检查该国家的地点地址。每个州都包含自己的 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