Tutorial ini menunjukkan cara membuat dan mengedit data lokasi. My Business Business Information API memberi Anda kemampuan untuk melakukan tindakan berikut:
- Membuat lokasi baru.
- Menghapus lokasi.
- Mendapatkan lokasi berdasarkan nama resource.
- Menampilkan daftar semua lokasi untuk akun.
- Memperbarui satu atau beberapa kolom untuk lokasi.
Lokasi dapat digunakan dalam Google Ads, tetapi harus diverifikasi agar memenuhi syarat untuk muncul di Penelusuran dan Maps. Data lokasi direpresentasikan oleh kumpulan accounts.locations.
Sebelum memulai
Sebelum menggunakan My Business Business Information API, Anda harus mendaftarkan aplikasi Anda dan mendapatkan kredensial OAuth 2.0. Untuk mengetahui detail cara mulai menggunakan My Business Business Information API, lihat Penyiapan dasar.
Membuat lokasi
Anda dapat menggunakan My Business Business Information API untuk membuat lokasi baru untuk bisnis dengan accounts.locations.create.
Untuk membuat lokasi, gunakan:
POST
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False
{
"storeCode": "GOOG-SYD",
"languageCode": "en-AU",
"title": "Google Sydney",
"phoneNumbers": {
"primaryPhone": "02 9374 4000"
}
"storefrontAddress": {
"addressLines": [
"Level 5",
"48 Pirrama Road"
],
"locality": "Pyrmont",
"postalCode": "2009",
"administrativeArea": "NSW",
"regionCode": "AU"
},
"websiteUri": "https://www.google.com.au/",
"regularHours": {
"periods": [
{
"openDay": "MONDAY",
"closeDay": "MONDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "TUESDAY",
"closeDay": "TUESDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "WEDNESDAY",
"closeDay": "WEDNESDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "THURSDAY",
"closeDay": "THURSDAY",
"openTime": "09:00",
"closeTime": "17:00"
},
{
"openDay": "FRIDAY",
"closeDay": "FRIDAY",
"openTime": "09:00",
"closeTime": "17:00"
}
]
},
"categories": {
"primaryCategory": {
"name": "gcid:software_company"
}
}
}
Menghapus lokasi
Anda dapat menggunakan My Business Business Information API untuk menghapus lokasi dengan locations.delete.
Untuk menghapus lokasi, gunakan:
DELETE
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}
Mendapatkan lokasi berdasarkan nama
Jika memiliki beberapa bisnis yang terkait dengan akun Anda, sebaiknya dapatkan hanya satu lokasi. Anda dapat memfilter berdasarkan nama bisnis untuk mendapatkan lokasi tertentu dengan locations.get.
Untuk mendapatkan lokasi berdasarkan nama, gunakan hal berikut. Anda harus menentukan readMask untuk mengambil kolom tertentu. :
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}
Menampilkan versi Google Maps
Agar dapat menampilkan versi Google Maps untuk lokasi, tambahkan
googleUpdated ke URL permintaan, seperti dalam contoh berikut:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}:googleUpdated?readMask={commaSeparatedFieldsToRetrieve}
Jika tidak ada hasil, kode status HTTP 404 NOT FOUND
ditampilkan. Detail selengkapnya tentang cara mengelola update Google dapat ditemukan di sini.
Menampilkan daftar lokasi
Saat mengelola satu atau beberapa lokasi, sebaiknya tampilkan daftar semua lokasi yang terkait dengan akun Anda. Gunakan API accounts.locations.list untuk menampilkan daftar semua lokasi yang terkait dengan pengguna.
Untuk menampilkan daftar semua lokasi untuk pengguna terautentikasi, gunakan hal berikut:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}
Memfilter hasil saat menampilkan daftar lokasi
Anda dapat menggunakan filter untuk membatasi hasil yang ditampilkan saat memanggil accounts.locations.list. Untuk memfilter permintaan, tambahkan ekspresi filter ke URL dasar seperti yang ditunjukkan dalam contoh berikut:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Sintaksis kueri dasar
Pembatasan memiliki sintaksis berikut: <field><operator><value>, dengan operator EQUALS (=) atau HAS (:). Operator EQUALS (=) dan HAS (:) setara untuk semua kolom kecuali locationName (lihat tabel di bawah).
Tanda kutip dienkode sebagai "%22" dan spasi sebagai tanda plus (+).
Kecuali jika dinyatakan lain, semua perbandingan adalah perbandingan token yang tidak peka huruf besar/kecil. Misalnya, "4 drive" akan cocok dengan "4, Privet Drive".
Menggabungkan beberapa kolom dalam kueri filter
API memungkinkan penggunaan AND untuk menghubungkan semua batasan kolom. Namun,
dalam hal kata kunci OR, semua batasan harus diterapkan ke kolom
yang sama. Misalnya: locationName=A OR labels=B tidak
diizinkan.
Contoh
Contoh berikut menunjukkan ekspresi filter yang menampilkan semua lokasi dengan nama "Pepé Le Pew." Filter ekspresi tersebut menunjukkan kategori untuk "french_restaurant" atau "european_restaurant", dan label "newly open."
locationName=%22Pepé+Le+Pew%22+AND+ (categories=%22french_restaurant%22+OR+ categories=%22european_restaurant%22)+AND+ labels=%22newly+open%22
Menelusuri berdasarkan jarak atau akun
Contoh berikut menunjukkan cara Anda dapat menelusuri lokasi dalam jarak tertentu dari suatu titik geografis:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
Untuk memfilter lokasi dalam radius 1000 mil dari Boulder, Colorado, AS:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=distance(latlng, geopoint(40.01, -105.27))<1000.0
Menampilkan daftar semua kolom filter yang didukung
Berikut adalah daftar lengkap semua kolom yang dapat digunakan untuk pemfilteran:
| Kolom | Deskripsi dan contoh |
|---|---|
| Kolom pencocokan string | |
title |
Nama bisnis yang sebenarnya
|
categories |
Kombinasi kategori utama dan kategori tambahan. Perhatikan bahwa "gcid:" harus dihapus. Jika ada beberapa kategori, filter ini akan cocok jika setidaknya satu kategori cocok dengan pola ini.
|
phone_numbers.primary_phone |
Nomor telepon utama dalam format E.164 (contoh: "+441234567890").
|
storefront_address.region_code |
Kode wilayah CLDR negara/wilayah alamat
|
storefront_address.administrative_area |
Sub-bagian administratif tertinggi yang digunakan untuk alamat pos negara atau wilayah
|
storefront_address.locality |
Bagian kota dalam alamat
|
storefront_address.postal_code |
Kode pos alamat
|
metadata.place_id |
Jika lokasi ini telah diverifikasi dan terhubung ke/muncul di Google Maps, kolom ini sama dengan ID tempat untuk lokasi.
|
openInfo.status |
Menunjukkan apakah Lokasi saat ini buka atau tidak (
|
labels |
Kumpulan string bentuk bebas yang memungkinkan Anda memberi tag pada bisnis Anda. Berbeda dengan semua kolom lainnya, nilai ini harus sama persis dengan label lengkap, termasuk kapitalisasi, dan bukan hanya token. Misalnya, label "XX YY" tidak akan cocok dengan "XX" atau "xx yy".
|
storeCode |
ID eksternal untuk lokasi ini, yang harus unik di dalam akun tertentu
|
| Fungsi | |
distance |
Memungkinkan Anda memfilter berdasarkan jarak lokasi dari suatu titik geografis.
|
Mengurutkan menurut kolom kueri
Anda dapat mengurutkan hasil berdasarkan nama bisnis atau kode toko dalam urutan menaik atau menurun. Beberapa kriteria pengurutan dipisahkan oleh koma dalam string
orderBy, seperti dalam contoh berikut:
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&orderBy=locationName,storeCode
Mem-patch lokasi
Gunakan My Business Business Information API untuk memperbarui satu atau beberapa kolom untuk lokasi dengan locations.patch.
Agar dapat mengubah satu atau beberapa kolom untuk lokasi, gunakan hal berikut:
Tambahkan kolom dan nilai yang diperbarui dengan kolom lokasi, dan gunakan
daftar kolom yang diperbarui yang dipisahkan koma sebagai nilai untuk fieldMask.
PATCH
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
"title": "Google Shoes"
}