辅助 API

每个辅助 API 端点均提供 cURL、Python 和 Node 示例：支持的国家和州、子类别目录，以及您的套餐涵盖的发布平台站点。

辅助端点提供 3 个参考目录，API 的其余部分会依据这些目录进行验证：支持哪些国家和州、有哪些商家类别，以及您的套餐涵盖哪些发布平台目录。这 3 个端点均为只读，不分页，且返回完整集合，因此使用 Read（读取）密钥即可，缓存比分页更重要。

端点概览

列出支持的国家和州

GET /countries

在 data.supportedCountries 下返回完整目录。每个国家均包含一个 ISO 代码、一个 base64 id、一个数值型 databaseId、一个条目各自带有 ISO 代码的 states 数组，以及 3 个地址标志：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      }    ]  }}

每条记录包含 5 个字段，使用哪个字段取决于它的用途。

一个地点在 subCategoryId 中接受 1 个主要类别，在 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 标志，每种类型最多只能有 1 个首选链接，并且在更新时接受值为 add 或 delete 的 action。有效类型、删除规则和同步行为均在地点操作链接中说明。

您可能遇到的错误

这些端点均不执行写入操作，因此使用 Read 密钥调用这些端点时，绝不会返回 SY90016。完整列表请参阅错误代码。

后续步骤

• 查询国家和类别：面向任务的指南，详细介绍如何衔接地点创建流程。
• 添加地点：介绍在何处使用 countryIso 和 subCategoryId。
• 查找并修复商家信息错误：使用套餐站点区分缺失的发布平台和出现故障的发布平台。
• 请参阅辅助 API 参考，查看全部 3 个端点的完整字段列表。