Listings APIListings API
登录

为无Google Business Profile的地点建档

在已连接的 Google 账号下，为地点提交全新的 Google Business Profile，然后通过该地点、其商家信息和 webhook 跟踪验证进度。

只有在 Google 商家信息已存在时，才能进行匹配和关联。新门店尚无 Google 商家信息，因此您需要请求 API 在已连接的 Google 账号下创建一条。创建过程是异步的，Google 会按自己的时间安排验证商家资料，因此本指南的大部分内容都围绕如何跟踪结果展开。

1. 确认地点尚无 Google 商家信息

读取该地点的高级商家信息，找到 site.name 为 Google Maps 的那一行。尚未在 Google 上展示的地点会显示 REQUIRING_ACTION，且 connectedAccountId 为 null。

Google row
curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/listings/premium \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "site": { "name": "Google Maps", "url": "maps.google.com" },  "syncStatus": "REQUIRING_ACTION",  "displayStatus": "Connect your account to sync the listing",  "listingUrl": null,  "connectedAccountId": null,  "verified": false}

如果该行已是 SYNCED，或已设置 connectedAccountId，则该地点已有 Google 商家信息，本指南不适用。请改为关联或更新现有商家信息。

2. 选择文件夹（可选）

Google 使用文件夹来组织账号下的商家信息，文件夹也称为账号组。列出已连接账号的文件夹；如果所有者希望将新商家资料放入特定组，请选择一个文件夹并将其作为 folderId 传入。跳过此步骤则会在账号根目录下创建商家资料。

Folders
curl https://listingsapi.com/api/v4/connected-accounts/4f712c17-4f95-42dd-90f4-97171a2e67b5/folders \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "getFoldersUnderGoogleAccount": [      { "folderId": "accounts/104890024806530350198", "folderName": "Bright Smile Dental", "locationCount": null }    ]  }}

请原样使用 folderId；它是 accounts/{id} 字符串，而非数字。当 Google 未返回 locationCount 时，其值可能为 null。此端点仅适用于 GoogleAccount 连接。

3. 创建商家信息

发送地点的 base64 id 和账号，如果选择了文件夹，也一并发送。响应仅表示请求已被接受。

Create listing
curl -X POST https://listingsapi.com/api/v4/locations/create/gmb-listing \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "input": {    "locationId": "TG9jYXRpb246MTgwMDI4OQ==",    "connectedAccountId": "4f712c17-4f95-42dd-90f4-97171a2e67b5",    "folderId": "accounts/104890024806530350198"  }}'
JSON
{  "data": {    "createGmbListingForLocation": { "clientMutationId": null, "success": true, "errors": null }  }}

success: true 表示已启动创建过程，并不表示商家资料已上线。Google 会在发布前审核每个新商家资料，这可能需要数天。当 success 为 false 时，errors 会说明原因：地点缺少必填字段、已有 Google 商家信息、已归档，或已连接的账号不再处于活跃状态。

4. 跟踪地点的验证状态

每次读取地点都会返回 googleVerificationStatus，其中包含 status 和 message。再次读取该地点，查看 Google 的处理进度。

Verification status
curl -G https://listingsapi.com/api/v4/locations-by-ids \--data-urlencode 'ids=["TG9jYXRpb246MTgwMDI4OQ=="]' \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "id": "TG9jYXRpb246MTgwMDI4OQ==",  "databaseId": 1800289,  "googleVerificationStatus": { "status": "PENDING_VERIFICATION", "message": null }}
status含义是否为终态
NOT_CONNECTED尚未关联 Google 商家信息。在步骤 3 生效之前，这是预期状态。否
NOT_VERIFIED商家信息已存在，验证尚未开始。否
PENDING_VERIFICATIONGoogle 正在验证该商家资料。否
UNDER_REVIEWGoogle 正在审核该商家资料。否
VERIFIED商家资料已上线。是
SUSPENDEDGoogle 已暂停该商家资料。是
DUPLICATEGoogle 判定该商家资料与现有商家资料重复。是
ERROR_WHILE_FETCHING无法从 Google 读取状态。请稍后重试。是

对于以天为单位推进的流程，每天读取一次即可。如果您同时检查多个地点，请在收到 429 时遵循 Retry-After。

5. 跟踪商家信息中的 Google 行

步骤 1 中的高级商家信息行会从商家信息侧跟踪同一进度。重新执行步骤 1 的调用，并读取 syncStatus、verified 和 listingUrl。

syncStatus含义
REQUIRING_ACTION尚未创建任何商家信息，或账号需要处理。请查看 displayStatus。
IN_PROGRESS已提交至 Google，正在等待响应。
PENDING_APPROVAL正在等待 Google 批准。
SYNCED已上线。listingUrl 已填充，connectedAccountId 指明账号。
FAILEDGoogle 拒绝了此次提交。syncIssue 会说明原因。

6. 监听验证 webhook

如果已在控制台中设置 webhook URL，则有 2 种事件涵盖终态，因此您无需轮询。这 2 种事件都携带 location_id，并且始终具有 data.connected_account_id: null。

事件触发条件data 字段
connection.google_verification_verified资料达到 VERIFIED 状态。platform: "google"
connection.google_verification_failed资料达到 SUSPENDED 或 DUPLICATE（failure_type: "rejected"）或 ERROR_WHILE_FETCHING（failure_type: "transient"）状态。platform, failure_type, reason
JSON
{  "event": "connection.google_verification_failed",  "timestamp": "2026-08-25T14:52:31Z",  "account_id": 11073,  "location_id": "279381",  "data": { "platform": "google", "connected_account_id": null, "failure_type": "rejected", "reason": "This profile is suspended." }}

只有 transient 失败值得重试。进行中的状态完全不会触发事件，因此没有收到事件不能作为判断依据：验证进行期间，请按照步骤 4 读取 googleVerificationStatus。

后续步骤