Listings APIListings API
登录

查询国家、州和类别

在创建地点之前，获取受支持的国家和州代码，将业务类别解析为对应的数字 id，并查看您的套餐涵盖哪些发布平台。

创建地点需要以下 3 项必须从 API 获取的值：API 接受的 countryIso 和 stateIso、数字形式的 subCategoryId，以及您希望限制发布平台时所需的套餐内站点 id。这些值由 3 个目录端点提供。这 3 个端点均返回普通数组，不进行分页。

1. 列出国家和州代码

GET /countries 返回所有受支持的国家，以及各国的 ISO 代码、hasCity 标志和 states 数组。创建和更新时，iso 的值用于填充 countryIso 和 stateIso。Python SDK 中对应的方法是 client.countries()，Node SDK 中是 client.fetchCountries()。

Countries
curl https://listingsapi.com/api/v4/countries \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "supportedCountries": [      {        "databaseId": 13,        "iso": "AU",        "name": "Australia",        "hasCity": true,        "states": [          { "id": "139", "iso": "VIC", "name": "Victoria" },          { "id": "142", "iso": "NSW", "name": "New South Wales" }        ]      },      {        "databaseId": 17,        "iso": "BE",        "name": "Belgium",        "hasCity": true,        "states": []      }    ]  }}

hasCity: true 表示创建时必须提供 city；为 false 时，您发送的城市会被丢弃。stateRequired: true 表示必须提供 stateIso，且其值必须是该国的 states 之一；为 false 时，请省略该字段。hasPostalCode: true 表示该国使用邮政编码，因此请随地址一起发送 postalCode。国家端点 说明了各个标志的含义。

2. 查找类别 id

GET /sub-categories 返回完整的类别目录。您作为 subCategoryId 发送的值应为整数 databaseId，而非 base64 格式的 id。例如，餐厅类别的值为 1432。请在您自己的代码中按名称筛选列表；服务端不提供搜索参数。

Find a category
curl https://listingsapi.com/api/v4/sub-categories \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.subcategories[] | select(.name | test("restaurant"; "i")) | {databaseId, name, primary}'
JSON
{  "data": {    "subcategories": [      {        "databaseId": 1432,        "id": "U3ViQ2F0ZWdvcnk6MTQzMg==",        "key": "restaurants",        "name": "Restaurants",        "primary": true      }    ]  }}
字段用途
databaseId作为 subCategoryId 发送的整数，或在 additionalCategoryIds 中发送的整数，后者最多可包含 9 个次要类别。
name便于阅读的标签，用于在选择器中显示和进行匹配。
key名称的 URL 友好型 slug，重命名后保持不变。
primary该类别是否可用作地点的主要子类别。为 subCategoryId 选择条目时，仅选择 true 条目。

3. 查看您的套餐涵盖哪些发布平台

GET /plan-sites 列出您套餐中的所有发布平台，并提供各平台的数字形式的 id、url、其接受的国家，以及其遵循 hideAddress 的国家。这些 id 是创建时 enabledSiteIds 和更新时 submissionDisabledSiteIds 唯一有效的值。请按地点所在国家进行筛选，以便仅提供接受该地点的发布平台。

Plan sites
curl https://listingsapi.com/api/v4/plan-sites \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.planSites[] | select(.supportedCountries | index("US")) | {id, name, url}'
JSON
{  "data": {    "planSites": [      {        "id": 1,        "name": "Google Maps",        "url": "maps.google.com",        "supportedCountries": ["US", "CA", "IN", "GB", "DE"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "IN", "GB"]      },      {        "id": 2,        "name": "Yelp",        "url": "yelp.com",        "supportedCountries": ["US", "CA", "GB", "DE", "FR"],        "hideAddressSupportedCountries": ["US", "CA", "AU", "GB"]      }    ]  }}

此处的 2 个国家数组均已截断；实际响应中，每个站点可能列出 50 个或更多代码。对于服务区域商家，还需检查 hideAddressSupportedCountries，因为即使发布平台接受该国家，也可能拒绝没有街道地址的商家信息。

4. 缓存这些查询结果

这 3 个目录很少变化，且均不分页，因此请在启动时各获取一次，将结果保存在内存或小型数据表中，并定期刷新。每次创建时都在流程中调用这些端点会消耗速率限额，却不会返回新数据；对于 Launch 套餐，这会占用每分钟 10 次请求额度中的 3 次。

目录大小刷新时机
国家数十个国家、数百个州很少需要刷新。每天刷新一次已绰绰有余。
子类别约 6,000 条每天刷新，或在创建因未知的 subCategoryId 而失败时刷新。
套餐站点数十个发布平台套餐变更时刷新，因为该列表的范围限定为您的套餐。

为子类别构建从小写 name 到 databaseId 的映射，并为国家构建从 countryIso 到 states 的映射。在调用创建操作之前，根据缓存验证地址，以便您的应用程序在发送请求之前发现不受支持的 countryIso（SY10036）或缺失的 city（SY10126）。

后续步骤