Listings APIListings API
登录

检查商家信息状态并获取上线链接

读取某个地点在每个发布平台上的同步状态，收集已上线商家信息的 URL，汇总覆盖情况，检查语音助手，并通过 webhook 接收通知，无需轮询。

地点创建后，系统会自动向您的套餐中的每个发布平台提交一条商家信息。本指南介绍如何查看每条商家信息的当前状态、获取已上线商家信息的 URL，以及在设置 webhook 后停止轮询。

1. 获取某个地点的高级商家信息

GET /locations/{locationId}/listings/premium 为套餐中的每个高级发布平台返回一条记录。返回结果是一个普通数组，而非分页列表。同级路由 /listings/additional 以相同结构返回免费目录；没有 listingType 查询参数。

Premium listings
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "listingsForLocation": [      {        "site": { "name": "Google Maps", "url": "maps.google.com" },        "syncStatus": "REQUIRING_ACTION",        "displayStatus": "Connect your account to sync the listing",        "actionRequired": true,        "listingUrl": null,        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:28Z"      },      {        "site": { "name": "BeLocalFocussed", "url": "belocalfocussed.com" },        "syncStatus": "SYNCED",        "displayStatus": "Synced",        "actionRequired": false,        "listingUrl": "https://belocalfocussed.com/jenny-home-26x0ffkd0e",        "syncIssue": null,        "lastUpdate": "2026-07-06T18:33:30Z"      }    ]  }}

每行将一个 site 与机器可读的 syncStatus 和便于人阅读的 displayStatus 对应起来。lastUpdate 表示该行上次更改的时间，有助于发现停滞的提交。

2. 读取每个发布平台的状态

syncStatus 是用于分支判断的字段。displayStatus 是向用户显示的文本，syncIssue 则在发布平台提供原因时包含该原因。

syncStatus含义应采取的操作
AVAILABLE已准备好提交，尚未开始。无需操作。系统会自动推进。
IN_PROGRESS已提交至发布平台，正在等待响应。请等待。如果已经过了几周，请检查 lastUpdate。
PENDING_APPROVAL发布平台已收到提交，正在审核。请等待。
SYNCED 或 COMPLETED已上线。listingUrl 已填充。收集链接（第 3 步）。
REQUIRING_ACTION需要您采取操作才能继续。actionRequired 为 true。请读取 displayStatus，然后参阅查找并修复商家信息错误。
FAILED发布平台拒绝了提交或无法处理提交。请读取 syncIssue，修正地点信息，然后重新轮询。
CANNOT_SUBMIT此发布平台完全无法接受此地点。通常是因为发布平台不支持该国家或类别。

在连接相应发布平台的账户之前，Google Maps 和 Facebook 的状态会一直保持为 REQUIRING_ACTION：Google Maps 需要连接 Google Business Profile，Facebook 需要连接 Facebook 公共主页。对于新地点，这是正常情况，并非故障。

Apple Maps 无需连接账户。如果所有者尚未连接经过验证的 Apple Business 组织账户，ListingsAPI 会通过其自己的 Apple Business Connect 账户提交地点，Apple 会在发布前验证该提交。请参阅连接 Apple Business Connect。

listingUrl 仅在已上线的行中设置。请筛选出 SYNCED（以及 COMPLETED），并将 URL 与网站名称一起保留，以便您显示一个“查看已上线商家信息”列表，或将其存储到您自己的对应记录中。

Live links
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '[.data.listingsForLocation[]       | select(.listingUrl != null)       | {site: .site.name, url: .listingUrl}]'

SYNCED 行的 listingUrl 为 null 的情况确实存在：某些目录不提供公开页面的 URL。请以状态为准，将链接视为可选项。

4. 生成覆盖情况汇总

按 syncStatus 统计行数，即可为每个地点生成一行健康状况数据：有多少个发布平台上的商家信息已上线，有多少个仍在处理中，以及有多少个受阻。这些统计数字适合显示在控制台上。

Coverage
curl -s https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.listingsForLocation      | group_by(.syncStatus)      | map({status: .[0].syncStatus, count: length})'

通过分页获取 GET /locations，并为每个地点调用一次高级商家信息端点，即可对多个地点执行此操作。每次调用都会计入您的速率限制，因此请在调用之间留出间隔，并在遇到 429 时遵循 Retry-After。查找并修复商家信息错误 展示了如何用此循环遍历一个账户内的所有地点。

5. 检查语音助手

语音助手（Google Assistant、Alexa、Siri、Cortana、Bixby）有专用端点 GET /locations/{locationId}/voice-assistants，其状态种类较少。Google Assistant 依赖 Google 连接，因此，没有 Google 连接的地点在这里也需要关注。Siri 的结果来自该地点的 Apple Maps 商家信息。

Voice assistants
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "voiceAssistantsForLocation": [      {        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "voiceIdentifier": "SIRI",        "name": "Siri",        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}
syncStatus含义
NOT_SUBMITTED尚未发送至语音助手。
IN_PROGRESS正在提交。
REQUIRING_ACTION需要您采取行动才能继续；请阅读 syncIssue。
LIVE已发布。

语音助手没有线上链接；LIVE 就是最终状态。

6. 接收 webhook 事件以替代轮询

如果您已在 /dashboard/webhooks 配置 webhook URL，那么每当某个地点向某个发布平台提交的任务达到终态时，都会触发 listing.submission 事件。该事件包含 status（success、incomplete 或 canceled）和站点，并在成功时包含 live_link，这与您在步骤 3 中收集的 URL 相同。

Route listing.submission
import base64 def handle(payload: dict) -> None:  if payload["event"] != "listing.submission":      return   data = payload["data"]  # "TG9jYXRpb246Mjc5Mzgx" -> "Location:279381"  global_id = base64.b64decode(data["location_id"]).decode()  database_id = int(global_id.split(":")[1])   site = data["site"]["name"]  status = payload["status"]   if status == "success":      live_link = payload.get("live_link")      save_live_link(database_id, site, live_link)  elif status == "incomplete":      flag_for_review(database_id, site, payload.get("error_message"))

请在 5 秒内返回 200，然后再执行处理工作；系统不会重试。有关接收器骨架代码和签名检查，请参阅通过 webhook 响应事件。

后续步骤