Listings APIListings API
登录

添加地点

使用发布平台所需的字段创建地点，处理验证错误，并确认地点已加入提交队列。

商家信息、评价、帖子和分析数据均以地点 ID 为关联键。POST /api/v4/locations 会创建地点，并为您套餐中的每个发布平台各生成一条商家信息，将其加入队列。

1. 收集必填字段

共有 10 个必填字段。服务区域商家也需要发送完整地址：使用 hideAddress: true 时，ListingsAPI 会存储地址，但不会将其提交给发布平台。发布平台会将省略的可选字段显示为空白，因此请发送您掌握的所有信息。

字段是否必填说明
name是2 至 150 个字符。
description是至少 200 个字符（SY10005）。
countryIso是受支持国家的双字母代码（SY10036）。
city是当该国家的 hasCity 为 true 时必填（SY10126）。当其为 false 时，您发送的城市会被丢弃。
subCategoryId是子类别列表中的数字 databaseId。
street是5 至 100 个字符（SY10011）。
stateIso是当该国家的 stateRequired 为 true 时必填，且必须是该国家的 states 之一（SY10010）。当 stateRequired 为 false 时，请省略此字段。
postalCode否可选，但只要该国家的 hasPostalCode 为 true，就应发送此字段。您发送的值必须符合该国家的格式（SY10014）。
phone是根据国家进行验证（SY10015）。
bizUrl是作为网站地址发布。部分发布平台会拒绝没有网站地址的商家信息。
storeId否您自己的门店代码，必须在整个账户内唯一。使用此代码即可再次查找该地点，无需存储我们的 ID。
businessHours否一周中的每一天各对应一个条目。格式请参阅更新地点。

2. 创建地点

POST /api/v4/locations 通过 JSON 请求体中的 input 对象接收这些字段。Python SDK 方法 locations.add() 以关键字参数的形式接收相同的字段，并在发送请求前验证必填字段。Node SDK 方法 createLocation() 直接接收 camelCase 对象。

Create
curl -X POST https://listingsapi.com/api/v4/locations \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "name": "Acme Kitchen",    "storeId": "ACME-NYC-001",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby farms. Open for lunch and dinner seven days a week, with takeout and delivery available.",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "businessHours": [      { "day": "MONDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "TUESDAY",   "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "THURSDAY",  "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "10:00pm" }] },      { "day": "FRIDAY",    "type": "OPEN",   "slots": [{ "start": "11:00am", "end": "11:00pm" }] },      { "day": "SATURDAY",  "type": "OPEN",   "slots": [{ "start": "12:00pm", "end": "11:00pm" }] },      { "day": "SUNDAY",    "type": "CLOSED", "slots": [] }    ]  }}'

3. 读取响应

创建成功时会返回 success: true，并在 data.createLocation.location 中返回新地点。请保留这两个标识符：id 是后续每次写入都需要使用的 base64 值，databaseId 则是控制台和 webhook 载荷中显示的数字值。

JSON
{  "data": {    "createLocation": {      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME-NYC-001",        "name": "Acme Kitchen",        "city": "New York",        "stateIso": "NY",        "countryIso": "US",        "status": "PENDING"      }    }  }}

地点处于验证和排队阶段时，status 为 PENDING。该状态会自动推进，无需再次调用 API。

4. 处理验证错误

创建操作可能在两个环节失败。格式错误的请求或无效密钥会导致返回 4xx，其中包含顶层 errors 数组。格式正确但包含 API 不接受的字段的请求会导致返回 200，其中包含 success: false，具体问题位于 data.createLocation.errors 中，因此请检查每次写入的响应体，而不仅仅是状态码。

JSON
{  "data": {    "createLocation": {      "success": false,      "errors": [        {          "code": "SY10005",          "message": "SY10005: description must be at least 200 characters",          "path": ["input", "description"]        }      ],      "location": null    }  }}

两个 SDK 都会在失败时抛出异常。Python 的 locations.add() 会在本地检查必填字段，并在发送请求前抛出 ValidationError。当 API 拒绝输入时，Node 的 createLocation() 会抛出 ValidationError，因此上面的示例没有检查成功标志。

您最常遇到的错误代码如下：

代码原因解决方法
SY10005缺少描述，或描述少于 200 个字符。编写更完整的描述。
SY10011缺少 street，或其长度少于 5 个字符。发送 street。
SY10010缺少 stateIso，或其值对该国家无效。发送从国家端点获取的州代码。
SY10036countryIso 不是受支持的国家。使用从国家端点获取的代码。
SY10126该国家要求提供 city，但此字段缺失。发送 city。
SY90016该密钥仅具有 Read 权限。使用 Write 密钥。

5. 确认提交已开始

创建地点后，系统会为套餐中的每个发布平台各排队一条商家信息。每条商家信息的初始状态为 AVAILABLE 或 IN_PROGRESS，在发布平台接受后变为 SYNCED，并附带 listingUrl。

Listing status
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI5MA==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"

配置 webhook 后，无需轮询。记录创建后会触发 profile.created 事件，而每个发布平台的状态发生变化时都会触发 listing.submission 事件。

后续步骤