Menggunakan data lokasi

Tutorial ini menunjukkan cara membuat dan mengedit data lokasi. My Business Business Information API memberi Anda kemampuan untuk melakukan tindakan berikut:

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:

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

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

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?readMask={commaSeparatedFieldsToRetrieve}

Menampilkan versi Google Maps

HTTP

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 yang dimiliki atau dikelola secara langsung oleh pengguna yang diautentikasi, gunakan opsi berikut:

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}

Gunakan karakter pengganti '-' untuk akun di URL permintaan untuk menyertakan listingan yang dimiliki secara tidak langsung (dimiliki atau dikelola melalui grup):

HTTP
GET
https://mybusinessbusinessinformation.googleapis.com/v1/accounts/-/locations?readMask={commaSeparatedFieldsToRetrieve}

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://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter={FIELD_NAME}=%22{YOUR_QUERY}%22

Sintaksis kueri dasar

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

HTTP
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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title:"Bajis" (cocok dengan nama lokasi apa pun dengan "Bajis" sebagai substring)

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=title="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://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=categories="french_restaurant"

phone_numbers.primary_phone

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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=phone_numbers.primary_phone="+441234567890"

storefront_address.region_code

Kode wilayah CLDR negara/wilayah alamat

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.region_code="US"

storefront_address.administrative_area

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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.administrative_area="CA"

storefront_address.locality

Bagian kota dalam alamat

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.locality="New York"

storefront_address.postal_code

Kode pos alamat

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storefront_address.postal_code="12345"

metadata.place_id

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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=metadata.place_id="12345"

openInfo.status

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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=openInfo.status="OPEN"

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&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://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=labels="newly open"

storeCode

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

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&filter=storeCode="12345"

Fungsi
distance

Memungkinkan Anda memfilter berdasarkan jarak lokasi dari suatu titik geografis.

https://mybusinessbusinessinformation.googleapis.com/v1/accounts/{accountId}/locations?readMask={commaSeparatedFieldsToRetrieve}&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://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:

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://mybusinessbusinessinformation.googleapis.com/v1/locations/{locationId}?languageCode=language&validateOnly=True|False&updateMask=title
{
    "title": "Google Shoes"
}