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 動作按鈕（訂購、外送、外帶、訂位、預約）。寫入模式是 append/upsert，而非取代：

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