Tutorial ini menunjukkan cara membuat dan mengedit data lokasi. Google My Business API memungkinkan Anda:
- Mendapatkan satu atau beberapa lokasi.
- 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 v4.accounts.locations.
Sebelum memulai
Sebelum menggunakan Google My Business API, Anda harus mendaftarkan aplikasi Anda dan mendapatkan kredensial OAuth 2.0. Untuk detail tentang cara memulai Google My Business API, lihat Penyiapan dasar.
Mendapatkan satu atau beberapa lokasi
Jika memiliki bisnis dengan satu atau beberapa lokasi, Anda sebaiknya memverifikasi lokasi untuk semua bisnis yang terkait dengan akun Anda. Gunakan API accounts.locations.batchGet untuk menampilkan daftar semua lokasi yang terkait dengan pengguna.
Untuk menampilkan daftar semua lokasi untuk pengguna terautentikasi, gunakan:
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet
{
"locationNames": [
"accounts/{accountId}/locations/{locationId}",
"accounts/{accountId}/locations/{locationId}"
],
}
Fungsi ini mengambil ArrayList<String> nama lokasi dan
menampilkan instance GetLocationsResponse, tempat Anda bisa mendapatkan
daftar
accounts.locations.
/*
* Returns the specified locations for a given account.
* @param accountName Name (resource path) of the account to get locations from.
* @param nameList List of location names to return.
* @return GetLocationsRequest Data model class containing results.
* @throws IOException.
*/
private static List<Location> batchGetLocations(String accountName, ArrayList<String> nameList) throws IOException {
GetLocationsRequest getLocationsRequest = new GetLocationsRequest();
getLocationsRequest.setLocationNames(nameList);
Mybusiness.Accounts.Locations.BatchGet locations =
mybusiness.accounts().locations().batchGet(accountName, getLocationsRequest);
GetLocationsResponse response = locations.execute();
return response.getLocations();
}
Data tambahan
Java API memberi Anda akses ke data kolom tambahan untuk instance lokasi. Gunakan metode berikut untuk menampilkan data tambahan tentang akun:
getAdditionalCategories()getAddress()getBusinessHours()getLabels()getLocationKey()getLocationName()getName()getPrimaryCategory()getPrimaryPhone()getServiceArea()getStoreCode()getWebsiteUrl()
Membuat lokasi
Anda dapat menggunakan API untuk membuat lokasi baru bisnis dengan accounts.locations.create.
Untuk membuat lokasi, gunakan:
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?requestId=requestId&validateOnly=True|False
{
"storeCode": "GOOG-SYD",
"languageCode": "en-AU",
"locationName": "Google Sydney",
"primaryPhone": "02 9374 4000",
"address": {
"addressLines": [
"Level 5",
"48 Pirrama Road"
],
"locality": "Pyrmont",
"postalCode": "2009",
"administrativeArea": "NSW",
"regionCode": "AU"
},
"websiteUrl": "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"
}
]
},
"primaryCategory": {
"categoryId": "gcid:software_company"
}
}
Fungsi ini membuat contoh lokasi baru untuk Google Sydney.
/**
* Creates a new location.
* @param accountName The name (resource path) of the account to create a
* location for.
* @return Location The data for the new location.
* @throws Exception
*/
public static Location createLocation(String accountName) throws Exception {
System.out.println("Creating Location");
// Street address
List<String> addressLines = new ArrayList();
addressLines.add("Level 5, 48 Pirrama Road");
Address address = new Address()
.setAddressLines(addressLines)
.setLocality("Pyrmont")
.setAdministrativeArea("NSW")
.setCountry("AU")
.setPostalCode("2009");
// Business hours
List<TimePeriod> periods = new ArrayList<>();
List<String> days = Arrays.asList("Monday", "Tuesday", "Wednesday", "Thursday", "Friday");
for (String day : days) {
TimePeriod period = new TimePeriod()
.setOpenDay(day)
.setOpenTime("9:00")
.setCloseTime("17:00")
.setCloseDay(day);
periods.add(period);
}
BusinessHours businessHours = new BusinessHours()
.setPeriods(periods);
Location location = new Location()
.setAddress(address)
.setRegularHours(businessHours)
.setLocationName("Google Sydney")
.setStoreCode("GOOG-SYD")
.setPrimaryPhone("02 9374 4000")
.setPrimaryCategory(new Category().setName("Software Company"))
.setWebsiteUrl("https://www.google.com.au/");
Mybusiness.Accounts.Locations.Create createLocation =
mybusiness.accounts().locations().create(accountName, location);
createLocation.setRequestId("1a84939c-ab7d-4581-8930-ee35af6fefac");
createLocation.setLanguageCode("en-AU");
Location createdLocation = createLocation.execute();
System.out.printf("Created Location:\n%s", createdLocation);
return createdLocation;
}
Menghapus lokasi
Anda dapat menggunakan API untuk menghapus lokasi dengan accounts.locations.delete.
Untuk menghapus lokasi, gunakan:
DELETE
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
{
"account": {
"accountName": "Anne Droyd"
},
"languageCode": "en",
"validateOnly": "true"
}
/**
* Deletes the specified location.
* @param locationName The name (resource path) of the location to delete.
* @throws Exception
*/
public static void deleteLocation(String locationName) throws Exception {
Location location = new Location();
location.setName(locationName);
Mybusiness.Accounts.Locations.Delete deleteLocation =
mybusiness.accounts().locations().delete(locationName);
deleteLocation.execute();
}
Mendapatkan lokasi berdasarkan nama
Jika memiliki beberapa bisnis yang terkait dengan akun Anda, ada kemungkinan Anda ingin mendapatkan hanya satu lokasi. Anda dapat memfilter berdasarkan nama bisnis untuk mendapatkan lokasi tertentu dengan akun.locations.get.
Untuk mendapatkan lokasi berdasarkan nama, gunakan:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
Fungsi ini mengambil daftar lokasi dan menampilkan data untuk akun yang ditentukan, jika ada.
/*
* Returns the specified location
* @param locationName The name (resource path) of the location to retrieve.
* @return Location The requested location.
*/
private static Location getLocationByName(String locationName) throws IOException {
Mybusiness.Accounts.Locations.Get location =
mybusiness.accounts().locations().get(locationName);
Location response = location.execute();
return response;
}
Data tambahan
Java API memberi Anda akses ke data kolom tambahan untuk instance lokasi. Gunakan metode berikut untuk menampilkan data tambahan tentang akun:
getAdditionalCategories()getAddress()getBusinessHours()getLabels()getLocationKey()getLocationName()getName()getPrimaryCategory()getPrimaryPhone()getServiceArea()getStoreCode()getWebsiteUrl()
Menampilkan versi Google Maps
Agar dapat menampilkan versi Google Maps untuk lokasi, tambahkan
googleUpdated ke URL permintaan, seperti dalam contoh berikut:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}:googleUpdated
Jika tidak ada hasil, kode status HTTP 404 NOT FOUND
ditampilkan.
Menampilkan daftar semua lokasi
Jika memiliki banyak bisnis yang terkait dengan akun Anda, ada kemungkinan Anda ingin memverifikasi semua lokasi. Gunakan API untuk mendapatkan semua lokasi dengan accounts.locations.list.
Untuk menampilkan semua lokasi, gunakan:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations
Fungsi ini menampilkan daftar lokasi untuk akun yang ditentukan.
/*
* Returns all locations for the specified account.
* @param accountName The account for which to return locations.
* @return List<Location> A list of all locations for the specified account.
*/
public static List<Location> listLocations(String accountName) throws Exception {
Mybusiness.Accounts.Locations.List locationsList =
mybusiness.accounts().locations().list(accountName);
ListLocationsResponse response = locationsList.execute();
List<Location> locations = response.getLocations();
if (locations != null) {
for (Location location : locations) {
System.out.println(location.toPrettyString());
}
} else {
System.out.printf("Account '%s' has no locations.", accountName);
}
return locations;
}
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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?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 "baru dibuka".
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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint({latitude}, {longitude}))<{distance}
Untuk memfilter lokasi dalam radius 1000 mil dari Boulder, Colorado, AS:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?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 | |
locationName |
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.
|
primaryPhone |
Nomor telepon utama dalam format E.164 (contoh: "+441234567890").
|
address.regionCode |
Kode wilayah CLDR negara/wilayah alamat
|
address.administrativeArea |
Sub-bagian administratif tertinggi yang digunakan untuk alamat pos negara atau wilayah
|
address.locality |
Bagian kota dalam alamat
|
address.postalCode |
Kode pos alamat
|
locationKey.placeId |
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
|
| Predikat | |
locationState.isPublished |
Menunjukkan apakah lokasi dipublikasikan ke Google Maps (
|
locationState.isGoogleUpdated |
Menunjukkan apakah ID tempat yang terkait dengan lokasi ini memiliki pembaruan (
|
locationState.isSuspended |
Menunjukkan apakah lokasi ditangguhkan (
|
locationState.isDuplicate |
Menunjukkan apakah lokasi merupakan duplikat lokasi lain (
|
| 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://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?orderBy=locationName,storeCode
Mem-patch lokasi
Gunakan API guna memperbarui satu atau beberapa kolom untuk lokasi dengan accounts.locations.patch.
Agar dapat mengubah satu atau beberapa kolom untuk lokasi, gunakan:
Tambahkan kolom dan nilai yang diperbarui dengan kolom lokasi, dan gunakan
daftar kolom yang diperbarui yang dipisahkan koma sebagai nilai untuk fieldMask.
PATCH
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=FIELD_NAME
{
"locationName": "Google Shoes",
"primaryPhone": "(212) 553-5558",
}
Fungsi ini memperbarui kolom locationName untuk
lokasi.
/**
* Updates the specified fields in the specified location.
* @param phone A string value for the location's primary phone.
* @param name The name (resource path) for the location to update.
* @throws Exception
*/
public static void updateLocation(String phone, String name) throws Exception {
Location location = new Location()
.setPrimaryPhone(phone);
Mybusiness.Accounts.Locations.Patch updateLocation =
mybusiness.accounts().locations().patch(name, location);
updateLocation.setFieldMask("primary_phone");
updateLocation.setLanguageCode("en-AU");
Location updatedLocation = updateLocation.execute();
System.out.printf("Updated Location:\n%s", updatedLocation);
}