Perhatian: Postingan yang terkait dengan COVID-19 sekarang diizinkan sementara untuk jaringan gerai. Selain itu, Google Bisnisku saat ini beroperasi dengan fungsi terbatas. Pelajari perubahan produk sementara lebih lanjut.

Menggunakan data lokasi

Tutorial ini menunjukkan cara membuat dan mengedit data lokasi. Google My Business API memungkinkan Anda:

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:

HTTP
POST
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations:batchGet

{
  "locationNames": [
    "accounts/{accountId}/locations/{locationId}",
    "accounts/{accountId}/locations/{locationId}"
  ],
}
Java

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:

HTTP
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"
    }
}
Java

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:

HTTP
DELETE
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
{
  "account": {
    "accountName": "Anne Droyd"
  },
  "languageCode": "en",
  "validateOnly": "true"
}

Java
/**
 * 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:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations/{locationId}
Java

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

HTTP

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:

HTTP
GET
https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations
Java

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

HTTP

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:

HTTP
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

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationName:"Bajis" (cocok dengan nama lokasi apa pun dengan "Bajis" sebagai substring)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationName="Bajis" (cocok dengan nama lokasi apa pun dengan "Bajis" sebagai token/kata)

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.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=categories="french_restaurant"

primaryPhone

Nomor telepon utama dalam format E.164 (contoh: "+441234567890").

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=primaryPhone="+441234567890"

address.regionCode

Kode wilayah CLDR negara/wilayah alamat

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.regionCode="US"

address.administrativeArea

Sub-bagian administratif tertinggi yang digunakan untuk alamat pos negara atau wilayah

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.administrativeArea="CA"

address.locality

Bagian kota dalam alamat

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.locality="New York"

address.postalCode

Kode pos alamat

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=address.postalCode="12345"

locationKey.placeId

Jika lokasi ini telah diverifikasi dan terhubung ke/muncul di Google Maps, kolom ini sama dengan ID tempat untuk lokasi.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationKey.placeId="12345"

openInfo.status

Menunjukkan apakah Lokasi saat ini buka atau tidak (OPEN, CLOSED_PERMANENTLY)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=openInfo.status="OPEN"

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=openInfo.status="CLOSED_PERMANENTLY"

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".

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=labels="newly open"

storeCode

ID eksternal untuk lokasi ini, yang harus unik di dalam akun tertentu

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=storeCode="12345"

Predikat
locationState.isPublished

Menunjukkan apakah lokasi dipublikasikan ke Google Maps (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isPublished="TRUE"

locationState.isGoogleUpdated

Menunjukkan apakah ID tempat yang terkait dengan lokasi ini memiliki pembaruan (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isGoogleUpdated="TRUE"

locationState.isSuspended

Menunjukkan apakah lokasi ditangguhkan (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isSuspended="TRUE"

locationState.isDuplicate

Menunjukkan apakah lokasi merupakan duplikat lokasi lain (TRUE, FALSE)

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=locationState.isDuplicate="TRUE"

Fungsi
distance

Memungkinkan Anda memfilter berdasarkan jarak lokasi dari suatu titik geografis.

https://mybusiness.googleapis.com/v4/accounts/{accountId}/locations?filter=distance(latlng, geopoint(1.0, -25.0))<1000.0

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:

HTTP
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:

HTTP

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",
}
Java

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);
  }