商家信息

每个商家信息端点均附有 cURL、Python 和 Node 示例，涵盖高级发布平台的同步状态、语音助手、按地点和按账户检测重复商家信息，以及重复商家信息屏蔽。

商家信息是一个地点在一个发布平台目录中的条目。创建地点时，系统会为套餐中的每个发布平台各排队一条商家信息，而商家信息端点可用于读取各条商家信息的当前状态、列出检测到的重复商家信息，以及确认或排除这些重复项。4 个 GET 端点可使用 Read（读取）密钥；2 个 POST 端点需要 Write（写入）密钥。

端点概览

方法	路径	功能	参考文档
`GET`	`/locations/{locationId}/listings/premium`	某个地点在每个高级发布平台上的同步状态。	获取高级商家信息
`GET`	`/locations/{locationId}/voice-assistants`	在 Google Assistant、Alexa、Siri、Cortana、Bixby 上的同步状态。	获取语音助手商家信息
`GET`	`/locations/listings/duplicates`	分页汇总一个账户内所有检测到的重复商家信息。	获取一个账户的所有重复商家信息
`GET`	`/locations/{locationId}/listings/duplicates`	一个地点的重复商家信息，按网站分组。	获取一个地点的重复商家信息
`POST`	`/locations/listings/mark-as-duplicate`	将商家信息条目确认为重复项，以便屏蔽。	将商家信息标记为重复项
`POST`	`/locations/listings/mark-as-not-duplicate`	将商家信息条目判定为误报并排除。	将商家信息标记为非重复项

读取高级发布平台商家信息状态

GET /locations/{locationId}/listings/premium

在 data.listingsForLocation 下，为该地点套餐中的每个高级发布平台返回一条记录。它是一个普通数组，而非分页列表。同级路径 /listings/additional 以相同结构返回免费目录；不存在 listingType 查询参数，向该路径传入此参数值会被忽略。

参数

名称	位置	是否必填	说明
`locationId`	path	是	Base64 格式的 id 或数字格式的 `databaseId`。

Premium listings

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

JSON

{  "data": {    "listingsForLocation": [      {        "id": "TGlzdGluZzoxMDQ0Njg3MjM=",        "site": { "databaseId": "1", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3Mjc=",        "site": { "databaseId": "387", "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"      },      {        "id": "TGlzdGluZzoxMDQ0Njg3MDk=",        "site": { "databaseId": "301", "name": "Local Mint", "url": "localmint.com" },        "syncStatus": "FAILED",        "displayStatus": "Partner experiencing issues; awaiting response",        "actionRequired": false,        "listingUrl": null,        "syncIssue": "Publisher requires website URL",        "lastUpdate": "2026-07-06T18:34:03Z"      }    ]  }}

根据 syncStatus 执行分支逻辑。向用户展示 displayStatus，读取 syncIssue 以了解发布平台给出的原因，并使用 lastUpdate 识别停滞的提交。仅已上线的记录会设置 listingUrl。

`syncStatus`	含义
`AVAILABLE`	已准备好同步，尚未开始。
`IN_PROGRESS`	已提交至发布平台，正在等待响应。
`PENDING_APPROVAL`	发布平台正在审核。
`SYNCED` 或 `COMPLETED`	已上线。`listingUrl` 已填充。
`REQUIRING_ACTION`	需要您采取行动才能继续。`actionRequired` 为 `true`；请读取 `displayStatus`。
`FAILED`	同步失败。请读取 `syncIssue`。
`CANNOT_SUBMIT`	此发布平台完全无法接收此地点。

在连接对应账号之前，Google Maps、Facebook 和 Waze 会一直保持 REQUIRING_ACTION 状态，并显示 displayStatus: "Connect your account to sync the listing"。对于新地点，这是预期行为。

读取语音助手状态

GET /locations/{locationId}/voice-assistants

在 data.voiceAssistantsForLocation 下，为每个语音助手返回一条记录：Google Assistant、Amazon Alexa、Apple Siri、Microsoft Cortana 和 Samsung Bixby。它是一个普通数组，状态种类比高级发布平台端点更少。

参数

名称	位置	是否必填	说明
`locationId`	path	是	Base64 格式的 id 或数字格式的 `databaseId`。

Voice assistants

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/voice-assistants \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "voiceAssistantsForLocation": [      {        "databaseId": "104468723",        "voiceIdentifier": "GOOGLE_ASSISTANT",        "name": "Google Assistant",        "connectedAccountId": null,        "syncStatus": "REQUIRING_ACTION",        "actionRequired": true,        "syncIssue": null,        "errors": []      },      {        "databaseId": "104468711",        "voiceIdentifier": "SIRI",        "name": "Siri",        "connectedAccountId": null,        "syncStatus": "IN_PROGRESS",        "actionRequired": false,        "syncIssue": null,        "errors": []      }    ]  }}

请标记所有 actionRequired 为 true 或已设置 syncIssue 的记录。errors 包含发布平台端的错误字符串，而在适用时，connectedAccountId 会指明用于同步的已连接账户。Google Assistant 的结果来自 Google Business Profile 连接，因此缺少 Google 连接是其需要处理的最常见原因。Siri 的结果来自该地点在 Apple Maps 上的商家信息。

`syncStatus`	含义
`NOT_SUBMITTED`	尚未发送至语音助手。
`IN_PROGRESS`	正在提交。
`REQUIRING_ACTION`	需要客户提供信息后才能继续同步。
`LIVE`	已发布。语音助手没有已上线商家信息的链接。

汇总账户内的重复商家信息

GET /locations/listings/duplicates

在 data.duplicateListingsRollup 下返回该密钥可见的所有已检测到的重复商家信息，涵盖账户内的所有地点和发布平台。它采用偏移量分页：输入 page 和 perPage，输出 records[] 以及 pageInfo.totalRecords、pageInfo.totalPages 和 pageInfo.hasNextPage。筛选条件使用平铺的查询参数，而非 JSON。未提供任何参数时，status 默认为 POTENTIAL，tag 默认为 all，因此不带参数的调用会返回账户内尚未关闭的重复商家信息。

参数

名称	位置	是否必填	说明
`status`	query	否	`POTENTIAL`（默认值）、`PROCESSING`、`FIXED` 或 `FAILED`。不区分大小写。任何其他值都会导致 `400`。
`siteId`	query	否	通过发布平台的数字站点 id（高级商家信息端点返回的 `site.databaseId`，或 plan-sites id），将范围缩小至单个发布平台。
`tag`	query	否	将汇总范围限定为单个标签。默认为 `all`。
`page`	query	否	从 1 开始的页码。默认为 `1`。
`perPage`	query	否	每页记录数。

Python 和 Node 封装仅提供 tag 和 page。如需按 status 或 siteId 筛选，或设置 perPage，请按照处理重复商家信息中的说明直接调用该路由。

Account rollup

curl "https://listingsapi.com/api/v4/locations/listings/duplicates?status=POTENTIAL&page=1&perPage=50" \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "duplicateListingsRollup": {      "pageInfo": {        "hasNextPage": true,        "hasPreviousPage": false,        "totalPages": 34,        "totalRecords": 1673      },      "records": [        {          "id": "3329229",          "name": "Woodbury Train Station",          "nameValid": false,          "duplicateProcessingState": "POTENTIAL",          "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",          "locationId": "73451",          "siteName": "City Squares",          "siteUrl": "citysquares.com"        }      ]    }  }}

汇总结果会告知您重复商家信息所在的位置：每条记录都列出 locationId 和 siteName。duplicateProcessingState 与按地点查询的端点通过 status 返回的生命周期状态相同。请逐页遍历，直到 hasNextPage 为 false；连续快速循环请求最容易触发 429。

状态	含义
`POTENTIAL`	已检测到，尚无人处理。
`PROCESSING`	已确认为重复商家信息，发布平台正在屏蔽该条目。
`FIXED`	发布平台已将其移除或合并。
`FAILED`	屏蔽未成功。请检查 `liveLink`。

列出单个地点的重复商家信息

GET /locations/{locationId}/listings/duplicates

在 data.duplicateListingsForLocation 下返回单个地点的所有已检测到的重复商家信息，并按发布平台站点分组。返回结果是一个普通数组。每个分组对应一个站点（name、url），包含一个 listings 数组，其中每个条目都带有 2 个标记端点均接受的 listingItemId。空数组表示未检测到任何重复商家信息。

参数

名称	位置	是否必填	说明
`locationId`	path	是	Base64 id 或数字形式的 `databaseId`。

Duplicates for a location

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/duplicates \-H "Authorization: API $LISTINGSAPI_KEY"

JSON

{  "data": {    "duplicateListingsForLocation": [      {        "id": "U2l0ZToxNTA=",        "name": "City Squares",        "url": "citysquares.com",        "listings": [          {            "id": "RHVwbGljYXRlOjIzNTk4NDUw",            "listingItemId": "TGlzdGluZ0l0ZW06MjM1OTg0NTA=",            "name": "Woodbury Train Station",            "liveLink": "http://citysquares.com/b/woodbury-train-station-23598450",            "status": "POTENTIAL"          }        ]      }    ]  }}

打开 liveLink 查看该条目，然后保留 listingItemId。在 Node SDK 中，应传递展平后的 d.id 值。status 使用与上述账户汇总相同的 4 个值。

将商家信息条目确认为重复项

POST /locations/listings/mark-as-duplicate

将商家信息条目标记为已确认的重复项，以便由发布平台屏蔽。请在 input 下发送 listingItemId 值，并将某个地点的所有已确认条目合并到一次调用中批量提交，而不是每个条目调用一次。这是一项写入操作，需要 Write（写入）密钥。

参数

名称	位置	是否必填	说明
`input.listingItemIds`	body	是	由重复商家信息端点返回的 base64 `listingItemId` 值组成的数组。
`input.locationId`	body	否	Base64 或数字形式的地点 id。将操作范围限定为单个地点。

Mark as duplicate

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

JSON

{  "data": {    "markAsDuplicate": {      "success": true,      "errors": null    }  }}

success: true 表示条目已被接受，并转为 PROCESSING。带有 success: false 的 200 或 400 会附带一个 errors 数组，其中各条目包含 code、message 和 path；这通常由未知或格式错误的 id 导致。Python SDK 会返回响应载荷；Node SDK 则会抛出 ValidationError，因此 promise 成功兑现即表示操作成功。

将商家信息条目排除为非重复项

POST /locations/listings/mark-as-not-duplicate

将潜在重复项判定为误报并予以排除。检测机制采取保守策略，会将同一特许经营品牌的其他门店、第 2 个合法商家资料或已更名的地点标记为潜在重复项。排除后，这些条目将不再出现在 2 个重复商家信息端点的结果中。它接受与上述端点完全相同的请求体，也可用于撤销对条目的错误标记。

参数

名称	位置	是否必填	说明
`input.listingItemIds`	body	是	由待排除条目的 base64 `listingItemId` 值组成的数组。
`input.locationId`	body	否	Base64 或数字形式的地点 id。将操作范围限定为单个地点。

Mark as not duplicate

curl -X POST https://listingsapi.com/api/v4/locations/listings/mark-as-not-duplicate \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "listingItemIds": ["TGlzdGluZ0l0ZW06MjM1OTg0NTA="]  }}'

JSON

{  "data": {    "markAsNotDuplicate": {      "success": true,      "errors": null    }  }}

响应为 data.markAsNotDuplicate，包含与标记为重复项的调用相同的 success 和 errors 字段。被排除的条目会被记录为已确认的非重复项，且不会在下一轮检测中再次出现。

您可能遇到的错误

代码或状态	含义	解决方法
`401`	API 密钥缺失或无效。	发送 `Authorization: API $LISTINGSAPI_KEY`。
账户汇总中的 `400`	`status` 不是 `POTENTIAL`、`PROCESSING`、`FIXED`、`FAILED` 中的任何一个。	使用这 4 个值中的一个。
标记端点上的 `400`	商家信息条目的 id 未知或格式错误。请阅读 `errors[].code` 和 `message`。	发送重复项端点返回的 `listingItemId` 值。
`200`，同时包含 `success: false`	请求已执行，但输入被拒绝。详细信息位于 `data.<op>.errors` 中。	检查每次写入操作的响应体，不要只检查状态。
`SY90016`（HTTP `400`）	写入操作使用了 Read 密钥。	对这 2 个标记端点使用 Write 密钥。
`429`	已超出速率限制。Launch 套餐允许每分钟发送 10 个请求。	等待 `Retry-After` 后再继续。请参阅速率限制。

所有代码均列于错误参考中。

后续步骤

查看商家信息状态和上线链接：用高级商家信息端点和语音助手端点的数据搭建覆盖情况控制台。
查找并修复商家信息错误：逐一处理 REQUIRING_ACTION 和 FAILED 行。
处理重复商家信息：使用 4 个重复项端点的审核流程，包括状态跟踪。
连接 Google 并导入地点：连接 Google Maps 和 Google Assistant 使用的 Google Business Profile。
连接 Apple Business Connect：通过所有者已验证的 Apple Business 账户向 Apple Maps 发布商家信息。
资源入口：商家信息。SDK 参考：Python 商家信息、Node 商家信息。