Tutorial ini menunjukkan cara membuat dan mengedit data lokasi. Google My Business API memberi Anda kemampuan untuk melakukan hal berikut:
- 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 mendapatkan 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 daftar semua lokasi untuk pengguna terautentikasi, gunakan hal berikut:
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet
{
"locationNames": [
"accounts/{accountId}/locations/{locationId}",
"accounts/{accountId}/locations/{locationId}"
],
}
Fungsi ini mengambil ArrayList<String> untuk 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 untuk bisnis dengan accounts.locations.create.
Untuk membuat lokasi, gunakan hal berikut:
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 hal berikut:
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, sebaiknya dapatkan satu lokasi. Anda dapat memfilter berdasarkan nama bisnis untuk mendapatkan lokasi tertentu dengan akun.locations.get.
Untuk mendapatkan lokasi berdasarkan nama, gunakan hal berikut:
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, sebaiknya verifikasikan semua lokasi. Gunakan API untuk mendapatkan semua lokasi dengan accounts.locations.list.
Untuk menampilkan semua lokasi, gunakan hal berikut:
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 ini:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter={FIELD_NAME}=%22{YOUR_QUERY}%22
Menggabungkan kolom dalam kueri filter
Batasan memiliki sintaksis berikut:
<field><operator><value>,
dengan operator EQUALS (=) atau HAS (:). Anda dapat menggunakan operator HAS (:)
untuk kolom berulang, seperti untuk
location.labels:"newly open" atau untuk pencocokan parsial. Jika tidak,
HAS sama dengan EQUALS. Untuk mencocokkan awalan, tambahkan bintang (*) setelah
nilai. Tanda kutip dienkode sebagai "%22" dan spasi sebagai tanda plus
(+).
API memungkinkan AND 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". Hal ini menunjukkan kategori untuk "french_restaurant" atau "european_restaurant," dan label "baru dibuka".
location.locationName=%22Pepé+Le+Pew%22+AND+
(location.categories=%22gcid:french_restaurant%22+OR+
location.categories=%22gcid:european_restaurant%22)+AND+
location.labels:%22newly+open%22
Menelusuri berdasarkan jarak atau akun
Contoh berikut menunjukkan bagaimana Anda dapat menelusuri lokasi dalam jarak tertentu dari titik geografis:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=location.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=location.distance(latlng, geopoint(40.01, -105.27))<1000.0
Mengurutkan menurut kolom kueri
Anda dapat mengurutkan hasil berdasarkan nama bisnis atau kode toko dalam urutan menaik
atau menurun. Beberapa kriteria pengurutan dipisah oleh koma dalam string
order_by, seperti dalam contoh berikut:
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?orderBy=locationName,storeCode
Kolom kueri lokasi
Anda dapat menggunakan setiap kolom untuk melihat daftar lokasi yang kolomnya yang sesuai cocok dengan nilai yang ditentukan. Anda juga dapat menambahkan batasan saat menggunakan kolom berikut:
| Kolom | Deskripsi dan contoh |
|---|---|
location.location_name |
Menampilkan daftar lokasi yang cocok dengan nama yang ditentukan.
|
location.distance |
Menampilkan daftar lokasi dalam jarak yang ditentukan dari titik geografis.
|
location.primary_phone |
Menampilkan daftar lokasi yang nomor telepon utamanya cocok dengan nilai yang ditentukan.
|
location.address.region_code |
Menampilkan daftar lokasi dalam kode daerah yang ditentukan.
|
location.address.administrative_area |
Menampilkan daftar lokasi yang wilayah administratifnya cocok dengan nilai yang ditentukan.
|
location.address.locality |
Menampilkan daftar lokasi yang lokalitasnya cocok dengan nilai yang ditentukan.
|
location.address.postal_code |
Menampilkan daftar lokasi dalam kode pos yang ditentukan.
|
location.open_info.status |
Menampilkan daftar lokasi yang statusnya cocok dengan nilai yang ditentukan
(contoh,
|
location.location_state.is_published |
Menampilkan daftar lokasi yang cocok dengan status yang ditentukan
(misalnya,
|
location.location_key.place_id |
Menampilkan daftar lokasi dengan ID yang cocok dengan nilai yang ditentukan.
|
Mem-patch lokasi
Gunakan API untuk memperbarui satu atau beberapa kolom untuk lokasi dengan accounts.locations.patch.
Untuk 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://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);
}