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 memberi Anda kemampuan untuk melakukan hal berikut:

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:

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

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 hal berikut:

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

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, sebaiknya verifikasikan semua lokasi. Gunakan API untuk mendapatkan semua lokasi dengan accounts.locations.list.

Untuk menampilkan semua lokasi, gunakan hal berikut:

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

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

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

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=location_name:"Bajis*"

location.distance

Menampilkan daftar lokasi dalam jarak yang ditentukan dari titik geografis.

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

location.primary_phone

Menampilkan daftar lokasi yang nomor telepon utamanya cocok dengan nilai yang ditentukan.

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=primary_phone="X"

location.address.region_code

Menampilkan daftar lokasi dalam kode daerah yang ditentukan.

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=address.region_code="US"

location.address.administrative_area

Menampilkan daftar lokasi yang wilayah administratifnya cocok dengan nilai yang ditentukan.

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=address.administrative_area="CA"

location.address.locality

Menampilkan daftar lokasi yang lokalitasnya cocok dengan nilai yang ditentukan.

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

location.address.postal_code

Menampilkan daftar lokasi dalam kode pos yang ditentukan.

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=address.postal_code="12345"

location.open_info.status

Menampilkan daftar lokasi yang statusnya cocok dengan nilai yang ditentukan (contoh, open, closed).

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=open_info.status="OPEN"

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=open_info.status="CLOSED_PERMANENTLY"

location.location_state.is_published

Menampilkan daftar lokasi yang cocok dengan status yang ditentukan (misalnya, true, false).

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=location.location_state.is_published="TRUE"

location.location_key.place_id

Menampilkan daftar lokasi dengan ID yang cocok dengan nilai yang ditentukan.

https://mybusiness.googleapis.com/v4/accounts/0123456789/locations?filter=location.location_key.place_id="12345"

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:

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