POST/api/v4/locations/update

更新地点

更新现有地点的可写字段。仅更改您发送的字段。

需要 API 密钥。请求头格式和密钥轮换请参阅身份验证。

参数

请求体

标记为必填的嵌套字段仅在您发送其父字段时适用。如果父字段为可选且您省略了它，其必填子字段不适用。

名称	类型	必填	描述
input.id	string	必填	The location's Base64-encoded Relay ID to update.
input.name	string	可选	Business name.
input.street	string	可选	Street address.
input.city	string	可选	City.
input.stateIso	string	可选	State/region ISO code.
input.postalCode	string	可选	Postal or ZIP code.
input.countryIso	string	可选	Two-letter country ISO code.
input.phone	string	可选	Primary phone number.
input.bizUrl	string	可选	Business website URL. Published to directories as the location's website.
input.primaryGbpSiteCategoryId	string	可选	Primary Google Business Profile category, as a GCID (e.g. `gcid:restaurant`). Resolved against `countryIso`, so send the two together.
input.additionalGbpSiteCategoryIds	array of strings	可选	Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrl	string	可选	URL of the menu, catalogue, or service list.
input.bookingUrl	string	可选	URL customers use to book an appointment.
input.reservationUrl	string	可选	URL customers use to make a reservation.
input.street1	string	可选	Second address line (suite, unit, floor).
input.latitude	string	可选	Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitude	string	可选	Longitude of the location, as a string. Send with `latitude`.
input.ownerEmail	string	可选	Email of the location owner. Used for listing claims and verification, not for login.
input.ownerName	string	可选	Name of the location owner.
input.facebookUrl	string	可选	URL of the location's Facebook page.
input.twitterUrl	string	可选	URL of the location's X (Twitter) profile.
input.linkedinUrl	string	可选	URL of the location's LinkedIn page.
input.instagramUrl	string	可选	URL of the location's Instagram profile.
input.youtubeUrl	string	可选	URL of the location's YouTube channel.
input.tiktokUrl	string	可选	URL of the location's TikTok profile.
input.pinterestUrl	string	可选	URL of the location's Pinterest profile.
input.tagline	string	可选	Short tagline for the business.
input.description	string	可选	Business description. Published to Google Business Profile as the business description.
input.yearOfIncorporation	string	可选	Year the business was incorporated, e.g. `2014`.
input.googleAdsPhone	string	可选	Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhones	array of strings	可选	Secondary phone numbers submitted to Google Business Profile.
input.videos	array of strings	可选	Video URLs for the location.
input.additionalCategoryIds	array of integers	可选	Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.subCategoryId	integer	可选	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.storeId	string	可选	Unique store code. Must be unique across the account.
input.enabledSiteIds	array of integers	可选	Site IDs to publish this location to, when you want a subset of your plan's sites. See the plan-sites endpoint for valid IDs. Omit to publish to every site in your plan.
input.updateOnlySiteIds	array of integers	可选	Restrict this update to the given site IDs. Other sites keep their current published values.
input.contentPreferredLanguage	string	可选	Preferred language for the location's published content, e.g. `ENGLISH`.
input.submissionDisabledSiteIds	array of integers	可选	Site IDs to exclude from submission. The inverse of `enabledSiteIds`, useful when you want every site in your plan except a few.
input.hideAddress	boolean	可选	Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosed	boolean	可选	Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItems	array of objects	可选	Services offered, published to Google Business Profile.
input.paymentMethods	array of strings	可选	Payment methods accepted. One or more of `VISA`, `MASTERCARD`, `AMEX`, `CASH`, `CHEQUE`, `CRYPTO`, `DINERS_CLUB`, `DISCOVER`, `FINANCING`, `INVOICE`, `TRAVELERS_CHECK`, `APPLE_PAY`, `SAMSUNG_PAY`, `PAYPAL`, `ANDROID_PAY`.
input.businessHours	array of objects	可选	Hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry. Send the full seven-day week when you set hours.
input.businessHours[].day	string	必填	One of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].type	string	必填	`OPEN` or `CLOSED`.
input.businessHours[].specialDate	string	可选	Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slots	array of objects	可选	Open intervals for the day, each `{ start, end }` (e.g. `09:00am`, `05:00pm`). Use an empty array when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	必填	Opening time for the interval, e.g. `09:00am`.
input.businessHours[].slots[].end	string	必填	Closing time for the interval, e.g. `05:00pm`.
input.moreHours	array of objects	可选	Additional hour sets (e.g. delivery, drive-through). Each entry is `{ hoursTypeId, moreHour }`, where `moreHour` is an array of `{ day, type, slots }` using the same shape as `businessHours` (minus `specialDate`).
input.serviceArea	object	可选	Service-area business config: `businessType`, `regionCode`, and a `placeInfos` array of `{ placeId, placeName }`.
input.customAttributes	array of objects	可选	Custom attribute values for the location. Each item is `{ slug, value }`, where `slug` identifies a custom attribute registered on your account and `value` is an array of strings. Sending a slug that is not registered returns `SY10035`. Registering a new custom attribute is not yet available through the API.
input.placeActionLinks	array of objects	可选	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean), optional `action` (`add`, the default, or `delete`), optional `name` (the link identifier returned by read endpoints once synced to Google). Only the links you reference are affected; links you don't include are left unchanged. See the Place Action Links guide.

请求示例

可直接粘贴的请求体。请将占位 ID 和值替换为您自己的。

Request body

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "phone": "5125550199",    "bizUrl": "https://acmekitchen.example.com",    "primaryGbpSiteCategoryId": "gcid:restaurant",    "businessHours": [      { "day": "MONDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "TUESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "WEDNESDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "THURSDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "FRIDAY", "type": "OPEN", "slots": [{ "start": "09:00am", "end": "05:00pm" }] },      { "day": "SATURDAY", "type": "OPEN", "slots": [{ "start": "10:00am", "end": "02:00pm" }] },      { "day": "SUNDAY", "type": "CLOSED", "slots": [] }    ]  }}

响应

200Location updated. `success` is true and the updated location summary is returned.

Response

{  "data": {    "updateLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI4OQ==",        "databaseId": 1800289,        "name": "Jenny Home",        "street": "600 Congress Ave, Suite 200",        "city": "Austin",        "stateIso": "TX",        "countryIso": "US",        "postalCode": "78701",        "phone": "5125550199",        "storeId": null,        "status": "APPROVED",        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.example.com", "isPreferred": true, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

401Unauthenticated, missing or invalid API key.

更新单个地点。仅修改 input 中包含的字段；所有省略的字段均保留当前值。id 是唯一的必填字段。

使用场景：更正电话号码。 仅发送 id 和 phone 即可修正联系方式，而不影响地址或营业时间。响应会返回更新后的地点，以便您确认新值已生效。

使用场景：发布完整的每周营业时间表。 发送包含 7 天的 businessHours 数组（如示例请求所示），以设置每天的营业时段。使用 { "day": "SUNDAY", "type": "CLOSED", "slots": [] } 标记不营业的日期。

营业时间规则。

提供全部 7 天；仅包含一周中部分日期的请求会被拒绝。
时间使用每个 slots 条目内的 start/end（例如 09:00am、05:00pm）；同一天内的时段不得重叠。
节假日和活动的特殊营业时间是包含 day: "SPECIAL" 和一个 specialDate（YYYY-MM-DD）的额外条目，需与一周 7 天的条目一同发送，绝不能替代这些条目。
仅在 businessHours 中使用 SPECIAL。moreHours 条目没有 specialDate 字段，因此其中标记为 SPECIAL 的一天不包含日期。
使用 moreHours 设置次要营业时间表（配送、免下车服务），以 hoursTypeId 为键。

始终发送完整的一周。 发布平台要求提供完整的 MONDAY–SUNDAY 时间表；每次设置 businessHours 时，都应发送全部 7 个条目，对于不营业的日期，使用 type: "CLOSED"（slots 为空），而不要省略该天。

注意事项。

标识符字段为 id（每个读取端点返回的 Base64 Relay ID）。
验证失败时，调用仍会返回 HTTP 200，并包含 success: false 和非空的 errors 数组；请务必检查 success，而不只是状态码。

地点操作链接

placeActionLinks 管理地点的 Google 操作按钮（订餐、配送、外带、订位、预约）。写入模式为追加／更新或插入，而非替换：

action: "add"（默认值）：添加新链接，或就地更新已保存链接的 uri/isPreferred。
action: "delete"：移除已保存的链接，并将从 Google 移除该链接的操作加入队列。
您在请求中未引用的链接将保持不变，省略链接绝不会将其移除。

链接的匹配方式（用于编辑／删除）：如果存在 name，则按该字段匹配，否则按 placeActionType + uri 匹配。如果您已获得 name（来自读取端点），请将其包含在请求中，以获得最准确的匹配；尚未同步到 Google 的链接没有 name，会按 placeActionType + uri 匹配。

placeActionType 的有效值： APPOINTMENT、ONLINE_APPOINTMENT、DINING_RESERVATION、FOOD_ORDERING、FOOD_DELIVERY、FOOD_TAKEOUT、SHOP_ONLINE。每种类型最多只能有 1 个首选链接。

更改链接的 URL = 在同一请求中移除旧链接 + 添加新链接：

JSON

{  "input": {    "id": "TG9jYXRpb246MTgwMDI4OQ==",    "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" }    ]  }}

刚完成写入时，链接的 name 和 submissionStatus 均为 null；链接同步到 Google 后，这些字段才会填充。请参阅地点操作链接指南，了解完整流程，包括直接在 Google 上发现的链接如何显示在 discoveredPlaceActionLinks 下。

Request

curl -X POST 'https://listingsapi.com/api/v4/locations/update' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "id": "TG9jYXRpb246MTgwMDI4OQ==",      "phone": "5125550199",      "bizUrl": "https://acmekitchen.example.com",      "primaryGbpSiteCategoryId": "gcid:restaurant",      "businessHours": [        {          "day": "MONDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "TUESDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "WEDNESDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "THURSDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "FRIDAY",          "type": "OPEN",          "slots": [            {              "start": "09:00am",              "end": "05:00pm"            }          ]        },        {          "day": "SATURDAY",          "type": "OPEN",          "slots": [            {              "start": "10:00am",              "end": "02:00pm"            }          ]        },        {          "day": "SUNDAY",          "type": "CLOSED",          "slots": []        }      ]    }  }'

Run in playground