POST/api/v4/locations/update

Memperbarui lokasi

Memperbarui field yang dapat ditulis pada lokasi yang sudah ada. Hanya field yang Anda kirim yang diubah.

Memerlukan kunci API. Lihat Autentikasi untuk format header dan rotasi kunci.

Parameter

Body

Field bersarang yang ditandai wajib hanya berlaku jika Anda mengirim induknya. Jika induknya opsional dan Anda menghilangkannya, field turunan yang wajib tidak berlaku.

Nama	Tipe	Wajib	Deskripsi
input.id	string	wajib	The location's Base64-encoded Relay ID to update.
input.name	string	opsional	Business name.
input.street	string	opsional	Street address.
input.city	string	opsional	City.
input.stateIso	string	opsional	State/region ISO code.
input.postalCode	string	opsional	Postal or ZIP code.
input.countryIso	string	opsional	Two-letter country ISO code.
input.phone	string	opsional	Primary phone number.
input.bizUrl	string	opsional	Business website URL. Published to directories as the location's website.
input.primaryGbpSiteCategoryId	string	opsional	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	opsional	Additional Google Business Profile categories, as GCIDs. Also resolved against `countryIso`.
input.offeringsUrl	string	opsional	URL of the menu, catalogue, or service list.
input.bookingUrl	string	opsional	URL customers use to book an appointment.
input.reservationUrl	string	opsional	URL customers use to make a reservation.
input.street1	string	opsional	Second address line (suite, unit, floor).
input.latitude	string	opsional	Latitude of the location, as a string. Send with `longitude`; publishers use it when the address alone is ambiguous.
input.longitude	string	opsional	Longitude of the location, as a string. Send with `latitude`.
input.ownerEmail	string	opsional	Email of the location owner. Used for listing claims and verification, not for login.
input.ownerName	string	opsional	Name of the location owner.
input.facebookUrl	string	opsional	URL of the location's Facebook page.
input.twitterUrl	string	opsional	URL of the location's X (Twitter) profile.
input.linkedinUrl	string	opsional	URL of the location's LinkedIn page.
input.instagramUrl	string	opsional	URL of the location's Instagram profile.
input.youtubeUrl	string	opsional	URL of the location's YouTube channel.
input.tiktokUrl	string	opsional	URL of the location's TikTok profile.
input.pinterestUrl	string	opsional	URL of the location's Pinterest profile.
input.tagline	string	opsional	Short tagline for the business.
input.description	string	opsional	Business description. Published to Google Business Profile as the business description.
input.yearOfIncorporation	string	opsional	Year the business was incorporated, e.g. `2014`.
input.googleAdsPhone	string	opsional	Alternate phone shown on Google Ads location extensions instead of `phone`.
input.additionalPhones	array of strings	opsional	Secondary phone numbers submitted to Google Business Profile.
input.videos	array of strings	opsional	Video URLs for the location.
input.additionalCategoryIds	array of integers	opsional	Secondary Listings API subcategory IDs, from the subcategories endpoint. Distinct from `additionalGbpSiteCategoryIds`, which takes Google GCIDs.
input.subCategoryId	integer	opsional	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.storeId	string	opsional	Unique store code. Must be unique across the account.
input.enabledSiteIds	array of integers	opsional	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	opsional	Restrict this update to the given site IDs. Other sites keep their current published values.
input.contentPreferredLanguage	string	opsional	Preferred language for the location's published content, e.g. `ENGLISH`.
input.submissionDisabledSiteIds	array of integers	opsional	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	opsional	Set `true` for a service-area business. ListingsAPI stores the address you send but does not submit it to publishers.
input.temporarilyClosed	boolean	opsional	Set `true` to stop publishing business hours while the location is temporarily closed.
input.serviceItems	array of objects	opsional	Services offered, published to Google Business Profile.
input.paymentMethods	array of strings	opsional	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	opsional	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	wajib	One of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY, or SPECIAL (a one-off override for the date in `specialDate`).
input.businessHours[].type	string	wajib	`OPEN` or `CLOSED`.
input.businessHours[].specialDate	string	opsional	Date of a one-off override, as `YYYY-MM-DD`. Set this only when `day` is `SPECIAL`.
input.businessHours[].slots	array of objects	opsional	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	wajib	Opening time for the interval, e.g. `09:00am`.
input.businessHours[].slots[].end	string	wajib	Closing time for the interval, e.g. `05:00pm`.
input.moreHours	array of objects	opsional	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	opsional	Service-area business config: `businessType`, `regionCode`, and a `placeInfos` array of `{ placeId, placeName }`.
input.customAttributes	array of objects	opsional	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	opsional	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.

Contoh permintaan

Body siap tempel. Ganti ID dan nilai placeholder dengan milik Anda.

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": [] }    ]  }}

Respons

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.

Memperbarui satu lokasi. Hanya field yang ada dalam input yang diubah; semua field yang Anda tidak sertakan tetap mempertahankan nilai saat ini. id adalah satu-satunya field yang wajib diisi.

Contoh penggunaan: memperbaiki nomor telepon. Kirim hanya id dan phone untuk memperbaiki detail kontak tanpa mengubah alamat atau jam operasional. Respons mengembalikan lokasi yang telah diperbarui agar Anda dapat memastikan nilai baru telah tersimpan.

Contoh penggunaan: memublikasikan jadwal mingguan lengkap. Kirim array businessHours untuk tujuh hari (seperti dalam contoh permintaan) guna menetapkan rentang waktu buka per hari. Tandai hari tutup dengan { "day": "SUNDAY", "type": "CLOSED", "slots": [] }.

Aturan jam operasional.

Sertakan ketujuh hari; jadwal yang hanya mencakup sebagian minggu akan ditolak.
Waktu menggunakan start/end di dalam setiap entri slots (e.g, 09:00am, 05:00pm); rentang waktu dalam satu hari tidak boleh tumpang tindih.
Pengaturan pengganti untuk hari libur dan acara berupa entri tambahan dengan day: "SPECIAL" dan sebuah specialDate (YYYY-MM-DD), yang dikirim bersama ketujuh entri hari dalam seminggu, tidak pernah sebagai penggantinya.
Gunakan SPECIAL hanya di dalam businessHours. Entri moreHours tidak memiliki field specialDate, sehingga hari SPECIAL di sana tidak menyertakan tanggal.
Gunakan moreHours untuk jadwal sekunder (pengantaran, layanan tanpa turun dari kendaraan), dengan hoursTypeId sebagai kunci.

Selalu kirim jadwal seminggu penuh. Platform publikasi mengharapkan jadwal MONDAY–SUNDAY yang lengkap; kirim ketujuh entri setiap kali Anda menetapkan businessHours, dengan menggunakan type: "CLOSED" (dengan slots kosong) untuk hari tanpa kegiatan operasional, alih-alih tidak menyertakan hari tersebut.

Hal yang perlu diperhatikan.

Field pengenal adalah id (ID Relay Base64 yang dikembalikan oleh setiap endpoint baca).
Jika validasi gagal, pemanggilan tetap mengembalikan HTTP 200 dengan success: false dan array errors yang berisi data; selalu periksa success, bukan hanya kode status.

Tautan tindakan tempat

placeActionLinks mengelola tombol tindakan Google untuk suatu lokasi (pemesanan, pengantaran, pesanan untuk dibawa pulang, reservasi, janji temu). Model penulisannya adalah append/upsert, bukan penggantian:

action: "add" (default): menambahkan tautan baru, atau memperbarui uri/isPreferred pada tautan yang sudah tersimpan secara langsung.
action: "delete": menghapus tautan yang tersimpan dan mengantrekan penghapusannya dari Google.
Tautan yang tidak Anda rujuk dalam permintaan tetap tidak berubah; tidak menyertakan tautan tidak pernah menghapusnya.

Cara tautan dicocokkan (untuk pengeditan/penghapusan): berdasarkan name jika ada, atau berdasarkan placeActionType + uri jika tidak ada. Sertakan name (dari endpoint baca) jika Anda memilikinya, untuk pencocokan yang paling akurat; tautan yang belum disinkronkan ke Google tidak memiliki name dan dicocokkan berdasarkan placeActionType + uri.

Nilai placeActionType yang valid: APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, SHOP_ONLINE. Maksimal satu tautan pilihan per jenis.

Mengubah URL tautan = menghapus tautan lama + menambahkan tautan baru dalam permintaan yang sama:

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" }    ]  }}

Segera setelah operasi penulisan, name dan submissionStatus pada tautan bernilai null; keduanya terisi setelah tautan disinkronkan ke Google. Lihat panduan Tautan Tindakan Tempat untuk alur lengkapnya, termasuk cara tautan yang ditemukan langsung di Google muncul di bawah 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