POST/api/v4/locations

Buat lokasi

Membuat lokasi bisnis baru di akun Anda dan memasukkannya ke antrean pengajuan profil bisnis.

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.name	string	wajib	Name of the business.
input.description	string	wajib	Business description, minimum 200 characters (`SY10005` when missing or shorter). Publishers use it as the primary listing copy.
input.storeId	string	opsional	Unique store code. Must be unique across the account.
input.street	string	wajib	Street address, 5 to 100 characters (`SY10011`).
input.city	string	wajib	City. Required where the country's `hasCity` is `true` (`SY10126`). Where it is `false`, a city you send is dropped.
input.stateIso	string	wajib	State ISO code. Required where the country's `stateRequired` is `true`, and must be one of that country's `states` (`SY10010`). Leave it out where `stateRequired` is `false`. See the countries and states endpoint for valid values.
input.postalCode	string	opsional	Postal code. Optional, but send it wherever the country's `hasPostalCode` is `true`. A value you send must match the country's format (`SY10014`).
input.countryIso	string	wajib	Country ISO code. Must be a supported country (`SY10036`). See the countries and states endpoint for valid values.
input.phone	string	wajib	Primary phone number, validated for the country (`SY10015`).
input.subCategoryId	integer	wajib	Primary subcategory ID. Pick a valid ID from the subcategories list endpoint.
input.bizUrl	string	wajib	Business website URL. Published to directories as the location's website. Some publishers refuse a listing without one.
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.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.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.customAttributes	array of objects	opsional	Publisher-specific attributes for the location.
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	Opening hours. Each entry is `{ day, type, slots }`, plus `specialDate` for a `SPECIAL` entry: `day` is an uppercase weekday enum (MONDAY–SUNDAY) or `SPECIAL`, `type` is `OPEN` or `CLOSED`, and `slots` is an array of `{ start, end }` time strings (e.g. `09:00am`, `05:00pm`). For a closed day use `type: "CLOSED"` with an empty `slots` array.
input.businessHours[].day	string	wajib	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 }`. Omit or leave empty when `type` is `CLOSED`.
input.businessHours[].slots[].start	string	wajib	Opening time, e.g. `09:00am`.
input.businessHours[].slots[].end	string	wajib	Closing time, e.g. `05:00pm`.
input.serviceArea	object	opsional	Service-area definition for service-area businesses: `{ businessType, regionCode, placeInfos: [{ placeId, placeName }] }`.
input.placeActionLinks	array of objects	opsional	Google action links (ordering, delivery, takeout, reservation, appointment). Each item: `placeActionType` (enum), `uri` (string), optional `isPreferred` (boolean). On create every link is new, so no `action` is needed. See the Place Action Links guide.
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.clientMutationId	string	opsional	Optional correlation token returned unchanged in the response. It does not prevent duplicate writes: the server does not detect repeated calls that reuse the same value.

Contoh permintaan

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

Request body

{  "input": {    "name": "Acme Kitchen",    "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",    "storeId": "ACME01",    "street": "123 Jump Street",    "city": "New York",    "stateIso": "NY",    "postalCode": "10013",    "countryIso": "US",    "phone": "6443859313",    "bizUrl": "https://acmekitchen.example.com",    "subCategoryId": 1432,    "primaryGbpSiteCategoryId": "gcid:restaurant",    "additionalGbpSiteCategoryIds": ["gcid:pizza_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": [] }    ],    "placeActionLinks": [      { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true },      { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com" }    ]  }}

Respons

200Location created successfully. Returns the new location as a summary object.

Response

{  "data": {    "createLocation": {      "clientMutationId": null,      "success": true,      "errors": null,      "location": {        "id": "TG9jYXRpb246MTgwMDI5MA==",        "databaseId": 1800290,        "storeId": "ACME01",        "name": "Acme Kitchen",        "street": "123 Jump Street",        "city": "New York",        "stateIso": "NY",        "postalCode": "10013",        "countryIso": "US",        "phone": "6443859313",        "status": "PENDING",        "primaryGbpSiteCategoryId": null,        "placeActionLinks": [          { "placeActionType": "FOOD_ORDERING", "uri": "https://order.acmekitchen.example.com", "isPreferred": true, "name": null, "submissionStatus": null },          { "placeActionType": "FOOD_TAKEOUT", "uri": "https://takeout.acmekitchen.example.com", "isPreferred": false, "name": null, "submissionStatus": null }        ],        "discoveredPlaceActionLinks": []      }    }  }}

400Bad request, validation failure (see `errors[]`).

401Unauthenticated, missing or invalid API key.

429Rate limit exceeded. Retry after the `Retry-After` header value.

Membuat lokasi bisnis baru. Jika berhasil, lokasi dimasukkan ke antrean pengajuan ke setiap platform publikasi dalam paketnya (atau, jika enabledSiteIds diberikan, hanya ke situs-situs tersebut). Field wajib: name, description dengan panjang minimal 200 karakter, subCategoryId, countryIso, dan, untuk negara dengan sistem pengalamatan tingkat kota, city. Lokasi juga memerlukan alamat jalan dan nomor telepon yang valid agar dapat dipublikasikan; berikan keduanya saat membuat lokasi agar tidak perlu melakukan pembaruan setelahnya.

id yang dikembalikan dienkode dalam base64 (e.g. TG9jYXRpb246MTgwMDI5MA==); dekode nilai tersebut untuk melihat bentuk internal Location:<databaseId>. Setiap panggilan berikutnya merujuk pada id dalam base64 ini.

Contoh penggunaan: menambahkan satu toko fisik beserta jam operasionalnya. Kirim alamat, phone, subCategoryId, dan array businessHours, dengan satu entri untuk setiap hari dalam seminggu yang berisi slot type: "OPEN" dan { start, end }, atau type: "CLOSED" dengan array slots kosong untuk hari tutup. Simpan kunci Anda sendiri di storeId agar nantinya Anda dapat menemukan lokasi melalui pengambilan berdasarkan kode toko tanpa perlu menyimpan ID dari Listings API.

Jam operasional khusus memerlukan jam operasional reguler. Jam operasional khusus (pengganti jam reguler untuk hari libur atau acara, dikirim sebagai entri businessHours dengan day: "SPECIAL", type: "OPEN" atau "CLOSED", serta specialDate dalam format YYYY-MM-DD) hanya dipublikasikan jika lokasi juga memiliki jadwal reguler MONDAY–SUNDAY; Google menolak lokasi yang diajukan dengan jam operasional khusus tanpa jam operasional reguler. Selalu sertakan jadwal businessHours lengkap untuk tujuh hari dalam seminggu setiap kali Anda menetapkan entri SPECIAL; lihat aturan jam operasional pada endpoint pembaruan untuk model lengkapnya.

Contoh penggunaan: memublikasikan ke sebagian situs. Berikan enabledSiteIds (ID situs dari endpoint plan-sites) untuk memublikasikan lokasi ke sebagian direktori yang dipilih, alih-alih seluruh direktori dalam paket; pola ini digunakan agensi untuk menjual cakupan situs bertingkat.

Tetapkan tombol tindakan Google saat membuat lokasi. Berikan placeActionLinks untuk menetapkan tombol tindakan Google milik lokasi (buat janji temu, pesan online, dan sebagainya) dalam panggilan yang sama. Nilai placeActionType yang valid adalah APPOINTMENT, ONLINE_APPOINTMENT, DINING_RESERVATION, FOOD_ORDERING, FOOD_DELIVERY, FOOD_TAKEOUT, dan SHOP_ONLINE, dengan maksimal satu tautan pilihan per jenis. Tepat setelah lokasi dibuat, name dan submissionStatus setiap tautan bernilai null hingga tautan tersebut disinkronkan ke Google. Untuk menambahkan, mengedit, atau menghapus tautan di kemudian hari, gunakan pembaruan lokasi; lihat panduan Place Action Links untuk model lengkapnya.

Kesalahan umum (dikembalikan sebagai 400 dengan detail di errors[]): description harus memiliki panjang minimal 200 karakter (SY10005), countryIso harus berupa negara yang didukung (SY10036), city wajib diisi untuk negara dengan sistem pengalamatan tingkat kota (SY10126), state harus berupa kode ISO yang valid, kode pos dan nomor telepon harus valid untuk negara tersebut, subCategoryId harus ada, dan storeId harus unik di seluruh akun. Setiap permintaan mengurangi kuota batas laju permintaan Anda dengan jumlah yang sama, apa pun endpoint-nya, sehingga penambahan lokasi dalam volume tinggi memicu 429 hanya berdasarkan jumlah permintaan; patuhi header Retry-After dan buat lokasi secara berurutan, bukan sekaligus dalam waktu singkat.

Request

curl -X POST 'https://listingsapi.com/api/v4/locations' \  -H "Authorization: API $LISTINGSAPI_KEY" \  -H 'Content-Type: application/json' \  -d '{    "input": {      "name": "Acme Kitchen",      "description": "Acme Kitchen is a family-owned neighborhood restaurant in downtown New York serving wood-fired pizza, hand-rolled pasta, and a short seasonal menu built around produce from nearby growers. Our dining room seats forty, takeout and delivery run until close, and the bar pours regional wine and beer on tap.",      "storeId": "ACME01",      "street": "123 Jump Street",      "city": "New York",      "stateIso": "NY",      "postalCode": "10013",      "countryIso": "US",      "phone": "6443859313",      "bizUrl": "https://acmekitchen.example.com",      "subCategoryId": 1432,      "primaryGbpSiteCategoryId": "gcid:restaurant",      "additionalGbpSiteCategoryIds": [        "gcid:pizza_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": []        }      ],      "placeActionLinks": [        {          "placeActionType": "FOOD_ORDERING",          "uri": "https://order.acmekitchen.example.com",          "isPreferred": true        },        {          "placeActionType": "FOOD_TAKEOUT",          "uri": "https://takeout.acmekitchen.example.com"        }      ]    }  }'

Run in playground