Listings APIListings API
登录

地点操作链接

通过 Listings API 管理地点的 Google 操作按钮（订购、配送、外带、订位、预约）。

地点操作链接是 Google 在商家资料上显示的操作按钮：在线订购、配送到家、预订餐桌、预约等。Listings API 将这些链接作为地点的一部分进行管理，因此您可以通过已经在使用的创建和更新端点设置这些链接，并且每个地点读取端点都会返回这些链接。

创建和更新操作均接受 input 上的 placeActionLinks 数组。每个元素如下：

字段类型是否必填说明
placeActionTypeenum是下列有效类型之一。
uristring是目标 URL。
isPreferredboolean否将此链接标记为其类型的首选链接。每种类型最多只能有 1 个首选链接。
actionstring否add（默认值）或 delete。仅在更新时使用。
namestring否链接的标识符，在链接同步到 Google 后由读取端点返回。写入时可选；如有此标识符，请将其包含在请求中，以便最准确地定位某个已保存的链接。

有效的 placeActionType 值：

Code
APPOINTMENT   ONLINE_APPOINTMENT   DINING_RESERVATIONFOOD_ORDERING   FOOD_DELIVERY   FOOD_TAKEOUT   SHOP_ONLINE

链接的匹配方式（用于编辑／删除）：如果存在 name，则按其匹配，否则按 placeActionType + uri 匹配。如果您已通过读取操作获取 name，请将其包含在请求中，以获得最准确的匹配结果。尚未同步到 Google 的新增链接没有 name，因此会按 placeActionType + uri 匹配。

操作

写入模型为追加／更新或插入，而非替换。更新时，仅影响您引用的链接；未包含的链接保持不变。

操作用途匹配方式
add添加新链接，或就地更新已保存链接的 uri／isPreferred。如果存在 name，则按其匹配，否则按 placeActionType + uri 匹配
delete移除已保存的链接，并排队将其从 Google 删除。如果存在 name，则按其匹配，否则按 placeActionType + uri 匹配

要更改链接的 URL，请在同一请求中移除旧链接并添加新链接（参见更改链接的 URL）。

系统支持通过以下 2 种方式填充地点的地点操作链接，并使其与 Google 保持同步。

流程 1：先在 Google 中创建，再连接

  1. 商家直接在其 Google Business Profile中设置地点操作链接。
  2. 该 Google Business Profile地点随后连接到 Listings API。
  3. 连接时，Listings API 会从 Google 获取当前线上链接，并将其纳入该地点的受管理链接集合。您无需通过 API 重新输入这些链接。

流程 2：先在 Listings API 中创建，再连接

  1. 在 Listings API 中创建地点时一并设置其地点操作链接（创建地点），或稍后添加这些链接（更新地点）。
  2. 连接到 Google Business Profile时，Listings API 会获取当前线上链接，并将其合并到受管理链接集合中：
    • 能够明确匹配的链接会加入受管理链接集合；
    • Google 中无法自动合并的任何链接（或尚未纳入受管理链接集合的链接）都会显示在 discoveredPlaceActionLinks 下，供您检查。
  3. 每次向 Google 提交时，Listings API 都会重新检查当前线上链接。在 Google Business Profile中直接发现的任何尚未由 Listings API 管理的新链接，都会被添加到 discoveredPlaceActionLinks。

已发现的链接是指存在于商家的 Google Business Profile中，但未在 Listings API 中管理的地点操作链接。上述流程会获取这些链接（连接时发现的额外链接，或后续提交时发现的新链接），所有读取端点都会将其与您管理的链接分开返回，放在 discoveredPlaceActionLinks 下（结构与 placeActionLinks 相同）：列表、按 IDs 查询、按门店代码查询和搜索。

JSON
{  "id": "TG9jYXRpb246MTgwMTAyMQ==",  "placeActionLinks": [ /* links you already manage */ ],  "discoveredPlaceActionLinks": [    {      "placeActionType": "APPOINTMENT",      "uri": "https://book.example.com",      "isPreferred": false,      "name": "locations/1944.../placeActionLinks/abc123",      "providerType": "MERCHANT",      "isEditable": true    }  ]}

要开始管理已发现的链接，请将其连同 action: "add" 一起发送到更新地点，调用方式与添加任何链接相同（通过 placeActionType + uri 标识）。其他链接保持不变。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.example.com", "isPreferred": false, "action": "add" }      ]    }  }'

此后，该链接会出现在 placeActionLinks 下，并从 discoveredPlaceActionLinks 中移除。您未纳入管理的已发现链接会继续列出（如果之后从 Google 中消失，则会自动从列表中移除）；无需执行任何操作。

示例

每次更新都会返回该地点完整的当前 placeActionLinks 集合（反映此次更改）。刚完成写入时，链接的 name 和 submissionStatus 均为 null；链接同步到 Google 后，这些字段才会填充。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

更改 URL 需要在同一请求中移除旧链接并添加新链接。如果旧链接已同步到 Google，请在 delete 中包含其 name，以实现最准确的匹配；否则会使用 placeActionType + uri。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com",     "name": "<link-name-if-synced>", "action": "delete" },        { "placeActionType": "FOOD_ORDERING", "uri": "https://new-order.example.com", "isPreferred": true, "action": "add" }      ]    }  }'

要仅更改 isPreferred（URL 不变），请连同 action: "add" 和新值一起重新发送该链接。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "<encoded-location-id>",      "placeActionLinks": [        { "placeActionType": "FOOD_DELIVERY", "uri": "https://deliver.example.com", "name": "<link-name-if-synced>", "action": "delete" }      ]    }  }'

创建时，每个链接都是新链接，因此 action 默认为 add。

Shell
curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Dental",      "description": "<business description, minimum 200 characters>",      "countryIso": "US",      "city": "New York",      "subCategoryId": 1432,      "placeActionLinks": [        { "placeActionType": "APPOINTMENT", "uri": "https://book.acmedental.example.com", "isPreferred": true },        { "placeActionType": "ONLINE_APPOINTMENT", "uri": "https://virtual.acmedental.example.com" }      ]    }  }'

说明

  • 每种类型最多只能有 1 个首选链接。
  • 链接的 submissionStatus 反映上次同步到 Google 的状态（success、failed 等），并附有人类可读的 submissionMessage。
  • Google 仅将地点操作链接应用于已验证的地点。