Text Search (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Developer Wilayah Ekonomi Eropa (EEA)

Pengantar

Text Search (Baru) menampilkan informasi tentang serangkaian tempat berdasarkan suatu string — misalnya, "pizza di Bandung" atau "toko sepatu di dekat Solo" atau "Jl. Rajawali 3". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi yang telah ditetapkan.

Layanan ini sangat berguna untuk membuat kueri alamat yang ambigu dalam sistem otomatis, dan komponen string non-alamat dapat mencocokkan bisnis serta alamat. Contoh kueri alamat yang ambigu adalah alamat yang diformat dengan buruk atau permintaan yang menyertakan komponen non-alamat seperti nama bisnis. Permintaan seperti dua contoh pertama dalam tabel berikut dapat menampilkan nol hasil kecuali jika lokasi — seperti wilayah, pembatasan lokasi, atau bias lokasi — ditetapkan.

"10 High Street, UK" atau "123 Main Street, US" Beberapa "High Street" di Inggris Raya; beberapa "Main Street" di Amerika Serikat. Kueri tidak menampilkan hasil yang diinginkan kecuali jika batasan lokasi ditetapkan.
"ChainRestaurant New York" Beberapa lokasi "ChainRestaurant" di New York; tidak ada alamat jalan atau bahkan nama jalan.
"10 High Street, Escher UK" atau "123 Main Street, Pleasanton US" Hanya ada satu "High Street" di kota Escher, Inggris Raya; hanya ada satu "Main Street" di kota Pleasanton, CA, Amerika Serikat.
"UniqueRestaurantName New York" Hanya ada satu tempat usaha dengan nama ini di New York; tidak perlu alamat jalan untuk membedakannya.
"restoran pizza di Jakarta" Kueri ini berisi batasan lokasi, dan "restoran pizza" adalah jenis tempat yang terdefinisi dengan baik. Fungsi ini menampilkan beberapa hasil.
"+1 514-670-8700"

Kueri ini berisi nomor telepon. API ini menampilkan beberapa hasil untuk tempat yang terkait dengan nomor telepon tersebut.

APIs Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:

Permintaan Text Search (Baru)

Permintaan Penelusuran Teks (Baru) adalah permintaan POST HTTP dengan bentuk berikut:

https://places.googleapis.com/v1/places:searchText

Teruskan semua parameter di isi permintaan JSON atau di header sebagai bagian dari permintaan POST. Contoh:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Respons Text Search (Baru)

Penelusuran Teks (Baru) menampilkan objek JSON sebagai respons. Dalam respons:

  • Array places berisi semua tempat yang cocok.
  • Setiap tempat dalam array direpresentasikan oleh objek Place. Objek Place berisi informasi mendetail tentang satu tempat.
  • FieldMask yang diteruskan dalam permintaan menentukan daftar kolom yang ditampilkan dalam objek Place.

Objek JSON lengkapnya berbentuk:

{
  "places": [
    {
      object (Place)
    }
  ]
}

Parameter wajib

  • FieldMask

    Tentukan daftar kolom yang akan ditampilkan dalam respons dengan membuat mask kolom respons. Teruskan mask kolom respons ke metode menggunakan parameter URL $fields atau fields, atau menggunakan header HTTP X-Goog-FieldMask. Tidak ada daftar kolom yang ditampilkan secara default dalam respons. Jika Anda menghapus mask kolom, metode akan menampilkan error.

    Penyamaran kolom merupakan praktik desain yang baik untuk memastikan Anda tidak meminta data yang tidak diperlukan, sehingga membantu menghindari waktu pemrosesan dan biaya penagihan yang tidak perlu.

    Tentukan daftar jenis data tempat yang dipisahkan koma yang akan ditampilkan. Misalnya, untuk mengambil nama tampilan dan alamat tempat.

    X-Goog-FieldMask: places.displayName,places.formattedAddress

    Gunakan * untuk mengambil semua kolom.

    X-Goog-FieldMask: *

    Tentukan satu atau beberapa kolom berikut:

    • Kolom berikut memicu SKU Text Search Essentials ID Only:

      places.attributions
      places.id
      places.name*
      nextPageToken

      * Kolom places.name berisi nama resource tempat dalam bentuk: places/PLACE_ID. Gunakan places.displayName di SKU Pro untuk mengakses nama tekstual tempat tersebut.

    • Kolom berikut memicu SKU Text Search Pro:

      places.accessibilityOptions
      places.addressComponents
      places.addressDescriptor*
      places.adrFormatAddress
      places.businessStatus
      places.containingPlaces
      places.displayName
      places.formattedAddress
      places.googleMapsLinks**
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.subDestinations
      places.types
      places.utcOffsetMinutes
      places.viewport

      * Deskripsi alamat umumnya tersedia untuk pelanggan di India dan bersifat eksperimental di tempat lain.

      ** Kolom places.googleMapsLinks berada dalam tahap Pratinjau pra-GA dan tidak ada biaya, yang berarti penagihan adalah $0, untuk penggunaan selama Pratinjau.

    • Kolom berikut memicu SKU Text Search Enterprise:

      places.currentOpeningHours
      places.currentSecondaryOpeningHours
      places.internationalPhoneNumber
      places.nationalPhoneNumber
      places.priceLevel
      places.priceRange
      places.rating
      places.regularOpeningHours
      places.regularSecondaryOpeningHours
      places.userRatingCount
      places.websiteUri

    • Kolom berikut memicu SKU Text Search Enterprise + Atmosphere:

      places.allowsDogs
      places.curbsidePickup
      places.delivery
      places.dineIn
      places.editorialSummary
      places.evChargeAmenitySummary
      places.evChargeOptions
      places.fuelOptions
      places.generativeSummary
      places.goodForChildren
      places.goodForGroups
      places.goodForWatchingSports
      places.liveMusic
      places.menuForChildren
      places.neighborhoodSummary
      places.parkingOptions
      places.paymentOptions
      places.outdoorSeating
      places.reservable
      places.restroom
      places.reviews
      places.reviewSummary
      places.routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Hanya Penelusuran Teks dan Penelusuran di Sekitar

  • textQuery

    String teks yang digunakan untuk menelusuri, misalnya: "restoran", "123 Main Street", atau "tempat terbaik untuk dikunjungi di San Francisco". API menampilkan kandidat hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.

Parameter opsional

  • includedType

    Membiaskan hasil ke tempat yang cocok dengan jenis yang ditentukan yang ditentukan oleh Tabel A. Hanya satu jenis yang dapat ditentukan. Contoh:

    • "includedType":"bar"
    • "includedType":"pharmacy"

    Penelusuran Teks (Baru) menerapkan pemfilteran jenis untuk kueri tertentu, bergantung pada penerapannya. Misalnya, pemfilteran jenis mungkin tidak diterapkan pada kueri untuk alamat tertentu ("123 Main Street"), tetapi pemfilteran jenis hampir selalu diterapkan pada kueri kategoris ("toko di sekitar" atau "pusat perbelanjaan").

    Untuk menerapkan pemfilteran jenis ke semua kueri, tetapkan strictTypeFiltering ke true.

  • includePureServiceAreaBusinesses

    Jika disetel ke true, respons mencakup bisnis yang melakukan kunjungan atau pengiriman langsung ke pelanggan, tetapi tidak memiliki lokasi bisnis fisik. Jika disetel ke false, API hanya menampilkan bisnis dengan lokasi bisnis fisik.

  • languageCode

    Bahasa yang digunakan untuk menampilkan hasil.

    • Lihat daftar bahasa yang didukung. Google sering memperbarui bahasa yang didukung, sehingga daftar ini mungkin tidak lengkap.
    • Jika languageCode tidak diberikan, API akan menggunakan en secara default. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
    • API ini berupaya sebaik mungkin untuk memberikan alamat jalan yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai tujuan tersebut, API ini menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasi ke dalam skrip yang dapat dibaca oleh pengguna jika perlu, dengan memperhatikan bahasa pilihan. Semua alamat lainnya ditampilkan dalam bahasa pilihan. Semua komponen alamat ditampilkan dalam bahasa yang sama, yang dipilih dari komponen pertama.
    • Jika nama tidak tersedia dalam bahasa pilihan, API akan menggunakan kecocokan terdekat.
    • Bahasa pilihan memiliki sedikit pengaruh pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan penampilannya. Geocoder menafsirkan singkatan secara berbeda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa, tetapi tidak dalam bahasa lain.

  • locationBias

    Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan.

    Anda dapat menentukan locationRestriction atau locationBias, tetapi tidak keduanya. Anggap locationRestriction sebagai penentuan region tempat hasil harus berada, dan locationBias sebagai penentuan region tempat hasil kemungkinan berada di dalam atau di dekatnya, tetapi dapat berada di luar area.

    Tentukan wilayah sebagai Viewport persegi panjang atau sebagai lingkaran.

    • Lingkaran ditentukan oleh titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Radius defaultnya adalah 0,0. Contoh:

      "locationBias": {
  "circle": {
    "center": {
      "latitude": 37.7937,
      "longitude": -122.3965
    },
    "radius": 500.0
  }
}

    • Persegi panjang adalah area tampilan lintang-bujur, yang ditampilkan sebagai dua titik rendah dan tinggi yang berlawanan secara diagonal. Titik rendah menandai sudut barat daya persegi panjang, dan titik tinggi merepresentasikan sudut timur laut persegi panjang.

      Area pandang dianggap sebagai area tertutup, yang berarti area pandang mencakup batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:

      • Jika low = high, area tampilan terdiri dari satu titik tersebut.
      • Jika low.longitude > high.longitude, rentang bujur terbalik (area tampilan melintasi garis bujur 180 derajat).
      • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang mencakup semua bujur.
      • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.
      • Jika low.latitude > high.latitude, rentang lintang kosong.

      Nilai rendah dan tinggi harus diisi, dan kotak yang ditampilkan tidak boleh kosong. Viewport kosong akan menyebabkan error.

      Misalnya, area tampilan ini sepenuhnya mencakup New York City:

      "locationBias": {
  "rectangle": {
    "low": {
      "latitude": 40.477398,
      "longitude": -74.259087
    },
    "high": {
      "latitude": 40.91618,
      "longitude": -73.70018
    }
  }
}

  • locationRestriction

    Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak ditampilkan.

    Tentukan wilayah sebagai Viewport persegi panjang. Untuk contoh menentukan Viewport, lihat deskripsi locationBias.

    Anda dapat menentukan locationRestriction atau locationBias, tetapi tidak keduanya. Anggap locationRestriction sebagai penentuan region tempat hasil harus berada, dan locationBias sebagai penentuan region tempat hasil kemungkinan berada di dalam atau di dekatnya, tetapi dapat berada di luar area.

  • maxResultCount (tidak digunakan lagi)

    Menentukan jumlah hasil (antara 1 dan 20) yang akan ditampilkan per halaman. Misalnya, menetapkan nilai maxResultCount sebesar 5 akan menampilkan hingga 5 hasil di halaman pertama. Jika ada lebih banyak hasil yang dapat ditampilkan dari kueri, respons akan menyertakan nextPageToken yang dapat Anda teruskan ke permintaan berikutnya untuk mengakses halaman berikutnya.

  • evOptions

    Menentukan parameter untuk mengidentifikasi konektor pengisi daya dan kecepatan pengisian daya kendaraan listrik (EV) yang tersedia.

    • connectorTypes

      Memfilter menurut jenis konektor pengisi daya kendaraan listrik yang tersedia di suatu tempat. Tempat yang tidak mendukung jenis konektor apa pun akan difilter. Jenis konektor pengisi daya EV yang didukung mencakup pengisi daya gabungan (AC dan DC), pengisi daya Tesla, pengisi daya yang kompatibel dengan GB/T (untuk pengisian daya cepat EV di China), dan pengisi daya stopkontak. Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi.

      • Untuk memfilter hasil konektor tertentu yang didukung, tetapkan connectorTypes ke nilai tersebut. Misalnya, untuk menemukan konektor tipe 1 J1772, tetapkan connectorTypes ke EV_CONNECTOR_TYPE_J1772.
      • Untuk memfilter hasil konektor yang tidak didukung, tetapkan connectorTypes ke EV_CONNECTOR_TYPE_OTHER.
      • Untuk memfilter hasil untuk semua jenis konektor yang merupakan stopkontak, tetapkan connectorTypes ke EV_CONNECTOR_TYPE_UNSPECIFIED_WALL_OUTLET.
      • Untuk memfilter hasil untuk jenis konektor apa pun, tetapkan connectorTypes ke EV_CONNECTOR_TYPE_UNSPECIFIED atau jangan tetapkan nilai untuk connectorTypes.

    • minimumChargingRateKw

      Memfilter tempat menurut kecepatan pengisian daya minimum kendaraan listrik dalam kilowatt (kW). Semua tempat yang mengenakan biaya pengisian daya kurang dari biaya pengisian daya minimum akan dikecualikan. Misalnya, untuk menemukan SPKLU dengan kecepatan pengisian daya minimal 10 kW, Anda dapat menyetel parameter ini ke "10".

  • minRating

    Membatasi hasil hanya pada hasil yang memiliki rating pengguna rata-rata lebih besar dari atau sama dengan batas ini. Nilai harus antara 0,0 dan 5,0 (inklusif) dengan kenaikan 0,5. Misalnya: 0, 0,5, 1,0, ... , 5,0 inklusif. Nilai dibulatkan ke atas ke 0,5 terdekat. Misalnya, nilai 0,6 akan menghilangkan semua hasil dengan rating kurang dari 1,0.

  • openNow

    Jika true, hanya menampilkan tempat yang buka pada saat kueri dikirim. Jika false, tampilkan semua bisnis terlepas dari status buka. Tempat yang tidak menetapkan jam buka dalam database Google Places akan ditampilkan jika Anda menetapkan parameter ini ke false.

  • pageSize

    Menentukan jumlah hasil (antara 1 dan 20) yang akan ditampilkan per halaman. Misalnya, menetapkan nilai pageSize sebesar 5 akan menampilkan hingga 5 hasil di halaman pertama. Jika ada lebih banyak hasil yang dapat ditampilkan dari kueri, respons akan menyertakan nextPageToken yang dapat Anda teruskan ke permintaan berikutnya untuk mengakses halaman berikutnya.

  • pageToken

    Menentukan nextPageToken dari isi respons halaman sebelumnya.

  • priceLevels

    Membatasi penelusuran ke tempat yang ditandai pada tingkat harga tertentu. Setelan defaultnya adalah memilih semua tingkat harga.

    Tingkat harga dapat diperkirakan untuk tempat dengan jenis berikut:

    Tempat dengan jenis yang tidak didukung tidak akan disertakan dalam respons jika priceLevels ditentukan.

    Tentukan array yang berisi satu atau beberapa nilai yang ditentukan oleh PriceLevel.

    Contoh:

    "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]

  • rankPreference

    Menentukan cara peringkat hasil dalam respons berdasarkan jenis kueri:

    • Untuk kueri kategori seperti "Restoran di New York City", RELEVANCE (peringkat hasil berdasarkan relevansi penelusuran) adalah defaultnya. Anda dapat menyetel rankPreference ke RELEVANCE atau DISTANCE (mengurutkan hasil menurut jarak).
    • Untuk kueri non-kategoris seperti "Mountain View, CA", sebaiknya Anda membiarkan rankPreference tidak ditetapkan.

  • regionCode

    Kode wilayah yang digunakan untuk memformat respons, ditentukan sebagai nilai kode CLDR dua karakter. Parameter ini juga dapat menimbulkan efek bias pada hasil penelusuran. Tidak ada nilai default.

    Jika nama negara di kolom formattedAddress dalam respons cocok dengan regionCode, kode negara akan dihapus dari formattedAddress. Parameter ini tidak berpengaruh pada adrFormatAddress, yang selalu menyertakan nama negara jika tersedia, atau pada shortFormattedAddress, yang tidak pernah menyertakannya.

    Sebagian besar kode CLDR identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk), sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "The United Kingdom of Great Britain and Northern Ireland"). Parameter dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  • strictTypeFiltering

    Digunakan dengan parameter includedType. Jika disetel ke true, hanya tempat yang cocok dengan jenis yang ditentukan oleh includeType yang akan ditampilkan. Jika salah (default), respons dapat berisi tempat yang tidak cocok dengan jenis yang ditentukan.

Contoh Text Search (Baru)

Menemukan tempat berdasarkan string kueri

Contoh berikut menunjukkan permintaan Penelusuran Teks (Baru) untuk "Spicy Vegetarian Food in Sydney, Australia":

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Perhatikan bahwa header X-Goog-FieldMask menentukan bahwa respons berisi kolom data berikut: places.displayName,places.formattedAddress. Responsnya kemudian dalam bentuk:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "29 King St, Sydney NSW 2000, Australia",
      "displayName": {
        "text": "Peace Harmony",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Tambahkan lebih banyak jenis data ke mask kolom untuk menampilkan informasi tambahan. Misalnya, tambahkan places.types,places.websiteUri untuk menyertakan jenis restoran dan alamat Web dalam respons:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia"
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.types,places.websiteUri' \
'https://places.googleapis.com/v1/places:searchText'

Respons sekarang dalam bentuk:

{
  "places": [
    {
      "types": [
        "vegetarian_restaurant",
        "vegan_restaurant",
        "chinese_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "websiteUri": "http://www.motherchusvegetarian.com.au/",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "types": [
        "vegan_restaurant",
        "thai_restaurant",
        "vegetarian_restaurant",
        "indian_restaurant",
        "italian_restaurant",
        "american_restaurant",
        "restaurant",
        "food",
        "point_of_interest",
        "establishment"
      ],
      "formattedAddress": "175 First Ave, Five Dock NSW 2046, Australia",
      "websiteUri": "http://www.veggosizzle.com.au/",
      "displayName": {
        "text": "Veggo Sizzle - Vegan & Vegetarian Restaurant, Five Dock, Sydney",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Memfilter tempat menurut tingkat harga

Gunakan opsi priceLevel untuk memfilter hasil ke restoran yang didefinisikan sebagai tidak mahal atau cukup mahal:

curl -X POST -d '{
  "textQuery" : "Spicy Vegetarian Food in Sydney, Australia",
  "priceLevels":["PRICE_LEVEL_INEXPENSIVE", "PRICE_LEVEL_MODERATE"]
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress,places.priceLevel' \
'https://places.googleapis.com/v1/places:searchText'

Contoh ini juga menggunakan header X-Goog-FieldMask untuk menambahkan kolom data places.priceLevel ke respons sehingga berbentuk:

{
  "places": [
    {
      "formattedAddress": "367 Pitt St, Sydney NSW 2000, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Mother Chu's Vegetarian Kitchen",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "115 King St, Newtown NSW 2042, Australia",
      "priceLevel": "PRICE_LEVEL_MODERATE",
      "displayName": {
        "text": "Green Mushroom",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Tambahkan opsi tambahan untuk mempersempit penelusuran Anda, seperti includedType, minRating, rankPreference, openNow, dan parameter lain yang dijelaskan dalam Parameter opsional.

Membatasi penelusuran ke area tertentu

Gunakan locationRestriction atau locationBias, tetapi jangan keduanya, untuk membatasi penelusuran ke suatu area. Anggap locationRestriction sebagai penentuan region yang harus berada dalam hasil, dan locationBias sebagai penentuan region yang harus berada di dekat hasil, tetapi dapat berada di luar area.

Membatasi area menggunakan locationRestriction

Gunakan parameter locationRestriction untuk membatasi hasil kueri ke wilayah yang ditentukan. Di isi permintaan, tentukan nilai garis lintang dan garis bujur low dan high yang menentukan batas wilayah.

Contoh berikut menunjukkan permintaan Text Search (Baru) untuk "makanan vegetarian" di New York City. Permintaan ini hanya menampilkan 10 hasil pertama untuk tempat yang buka.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "pageSize" : "10",
  "locationRestriction": {
    "rectangle": {
      "low": {
        "latitude": 40.477398,
        "longitude": -74.259087
      },
      "high": {
        "latitude": 40.91618,
        "longitude": -73.70018
      }
    }
  }
}' \
  -H 'Content-Type: application/json' \
  -H 'X-Goog-Api-Key: API_KEY' \
  -H 'X-Goog-FieldMask: places.id,places.formattedAddress' \
  'https://places.googleapis.com/v1/places:searchText'

Membiaskan ke suatu area menggunakan locationBias

Contoh berikut menunjukkan permintaan Penelusuran Teks (Baru) untuk "makanan vegetarian" yang cenderung ke lokasi dalam jarak 500 meter dari suatu titik di pusat kota San Francisco. Permintaan ini hanya menampilkan 10 hasil pertama untuk tempat yang buka.

curl -X POST -d '{
  "textQuery" : "vegetarian food",
  "openNow": true,
  "pageSize": 10,
  "locationBias": {
    "circle": {
      "center": {"latitude": 37.7937, "longitude": -122.3965},
      "radius": 500.0
    }
  },
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Menelusuri pengisi daya EV dengan kecepatan pengisian daya minimum

Gunakan minimumChargingRateKw dan connectorTypes untuk menelusuri tempat dengan pengisi daya yang tersedia dan kompatibel dengan kendaraan listrik Anda.

Contoh berikut menunjukkan permintaan untuk konektor pengisi daya EV tipe 1 Tesla dan J1772 dengan kecepatan pengisian daya minimum 10 kW di Mountain View, CA. Hanya empat hasil yang ditampilkan.

curl -X POST -d '{
    "textQuery": "EV Charging Station Mountain View",
    "pageSize": 4,
    "evOptions": {
      "minimumChargingRateKw": 10,
      "connectorTypes": ["EV_CONNECTOR_TYPE_J1772","EV_CONNECTOR_TYPE_TESLA"]
    }
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.displayName,places.evChargeOptions" \
'https://places.googleapis.com/v1/places:searchText'

Permintaan ini menampilkan respons berikut:

{
  "places": [
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 16,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 100,
            "count": 8,
            "availableCount": 5,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 2,
            "availableCount": 2,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 6,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 6,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 100,
            "count": 4,
            "availableCount": 3,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 350,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 2,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "EVgo Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 5,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_J1772",
            "maxChargeRateKw": 3.5999999046325684,
            "count": 1,
            "availableCount": 0,
            "outOfServiceCount": 1,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CHADEMO",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          },
          {
            "type": "EV_CONNECTOR_TYPE_CCS_COMBO_1",
            "maxChargeRateKw": 50,
            "count": 2,
            "availableCount": 0,
            "outOfServiceCount": 0,
            "availabilityLastUpdateTime": "2024-01-10T19:10:00Z"
          }
        ]
      }
    },
    {
      "displayName": {
        "text": "Electric Vehicle Charging Station",
        "languageCode": "en"
      },
      "evChargeOptions": {
        "connectorCount": 10,
        "connectorAggregation": [
          {
            "type": "EV_CONNECTOR_TYPE_OTHER",
            "maxChargeRateKw": 210,
            "count": 10
          }
        ]
      }
    }
  ]
}

Menelusuri bisnis jasa sistem panggilan

Gunakan parameter includePureServiceAreaBusinesses untuk menelusuri bisnis tanpa alamat layanan fisik (misalnya, layanan pembersihan keliling atau truk makanan).

Contoh berikut menunjukkan permintaan untuk tukang ledeng di San Francisco:

curl -X POST -d '{
  "textQuery" : "plumber San Francisco",
  "includePureServiceAreaBusinesses": true
}' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H 'X-Goog-FieldMask: places.displayName,places.formattedAddress' \
'https://places.googleapis.com/v1/places:searchText'

Dalam respons, bisnis tanpa alamat layanan fisik tidak menyertakan kolom formattedAddress:

{
  "places": [
    {
      "formattedAddress": "3450 Sacramento St #204, San Francisco, CA 94118, USA",
      "displayName": {
        "text": "Advanced Plumbing & Drain",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "1455 Bancroft Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Magic Plumbing Heating & Cooling",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "78 Dorman Ave, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Cabrillo Plumbing, Heating & Air",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "540 Barneveld Ave # D, San Francisco, CA 94124, USA",
      "displayName": {
        "text": "Mr. Rooter Plumbing of San Francisco",
        "languageCode": "en"
      }
    },
    /.../
    {
      "displayName": {
        "text": "Pipeline Plumbing",
        "languageCode": "en"
      }
    },
    {
      "formattedAddress": "350 Bay St #100-178, San Francisco, CA 94133, USA",
      "displayName": {
        "text": "One Source Plumbing and Rooter",
        "languageCode": "en"
      }
    },
    /.../
  ]
}

Tentukan jumlah hasil yang akan ditampilkan per halaman

Gunakan parameter pageSize untuk menentukan jumlah hasil yang akan ditampilkan per halaman. Parameter nextPageToken di isi respons memberikan token yang dapat digunakan dalam panggilan berikutnya untuk mengakses halaman hasil berikutnya.

Contoh berikut menunjukkan permintaan untuk "pizza di New York" yang dibatasi hingga 5 hasil per halaman:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJifIePKtZwokRVZ-UdRGkZzs"
    },
    {
      "id": "ChIJPxPd_P1YwokRfzLhSiACEoU"
    },
    {
      "id": "ChIJrXXKn5NZwokR78g0ipCnY60"
    },
    {
      "id": "ChIJ6ySICVZYwokR9rIK8HjXhzE"
    },
    {
      "id": "ChIJ6xvs94VZwokRnT1D2lX2OTw"
    }
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Untuk mengakses halaman hasil berikutnya, gunakan pageToken untuk meneruskan nextPageToken di isi permintaan:

 curl -X POST -d '{
  "textQuery": "pizza in New York",
  "pageSize": 5,
  "pageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
  }' \
-H 'Content-Type: application/json' -H 'X-Goog-Api-Key: API_KEY' \
-H "X-Goog-FieldMask: places.id,nextPageToken" \
'https://places.googleapis.com/v1/places:searchText'

{
  "places": [
    {
      "id": "ChIJL-LN1N1ZwokR8K2jACu6Ydw"
    },
    {
      "id": "ChIJjaD94kFZwokR-20CXqlpy_4"
    },
    {
      "id": "ChIJ6ffdpJNZwokRmcafdROM5q0"
    },
    {
      "id": "ChIJ8Q2WSpJZwokRQz-bYYgEskM"
    },
    {
      "id": "ChIJ8164qwFZwokRhplkmhvq1uE"
    }
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Mendapatkan deskriptor alamat

Deskripsi alamat memberikan informasi relasional tentang lokasi suatu tempat, termasuk bangunan terkenal di sekitar dan area yang mencakupnya.

Contoh berikut menunjukkan permintaan Penelusuran Teks (Baru) untuk tempat di dekat mal di San Jose. Dalam contoh ini, Anda menyertakan addressDescriptors dalam mask kolom:

curl -X POST -d '{
  "textQuery": "clothes",
  "maxResultCount": 5,
  "locationBias": {
    "circle": {
      "center": {
        "latitude": 37.321328,
        "longitude": -121.946275
      }
    }
  },
  "rankPreference":"RANK_PREFERENCE_UNSPECIFIED"
}' \
-H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.displayName,places.addressDescriptor" \
https://places.googleapis.com/v1/places:searchText

Respons mencakup tempat yang ditentukan dalam permintaan, daftar landmark terdekat dan jaraknya dari tempat tersebut, serta daftar area dan hubungan penampungannya dengan tempat tersebut:

  {
  "places": [
    {
      "displayName": {
        "text": "Urban Outfitters",
        "languageCode": "en"
      },
      "addressDescriptor": {
        "landmarks": [
          {
            "name": "places/ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "placeId": "ChIJVVVVUB7Lj4ARXyb4HFVDV8s",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "food",
              "movie_theater",
              "point_of_interest",
              "restaurant",
              "shoe_store",
              "shopping_mall",
              "store"
            ],
            "spatialRelationship": "WITHIN",
            "straightLineDistanceMeters": 133.72855
          },
          {
            "name": "places/ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "placeId": "ChIJ62_oCR7Lj4AR_MGWkSPotD4",
            "displayName": {
              "text": "Nordstrom",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 250.99161
          },
          {
            "name": "places/ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "placeId": "ChIJ8WvuSB7Lj4ARFyHppkxDRQ4",
            "displayName": {
              "text": "Macy's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "point_of_interest",
              "store"
            ],
            "straightLineDistanceMeters": 116.24196
          },
          {
            "name": "places/ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "placeId": "ChIJ9d3plB_Lj4ARzyaU5bn80WY",
            "displayName": {
              "text": "Bank of America Financial Center",
              "languageCode": "en"
            },
            "types": [
              "bank",
              "establishment",
              "finance",
              "point_of_interest"
            ],
            "straightLineDistanceMeters": 121.61515
          },
          {
            "name": "places/ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "placeId": "ChIJaXCjxvXLj4ARCPmQpvJ52Lw",
            "displayName": {
              "text": "Bloomingdale's",
              "languageCode": "en"
            },
            "types": [
              "clothing_store",
              "department_store",
              "establishment",
              "furniture_store",
              "home_goods_store",
              "point_of_interest",
              "shoe_store",
              "store"
            ],
            "straightLineDistanceMeters": 81.32396
          }
        ],
        "areas": [
          {
            "name": "places/ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "placeId": "ChIJb3F-EB7Lj4ARnHApQ_Hu1gI",
            "displayName": {
              "text": "Westfield Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "placeId": "ChIJXYuykB_Lj4AR1Ot8nU5q26Q",
            "displayName": {
              "text": "Valley Fair",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          },
          {
            "name": "places/ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "placeId": "ChIJtYoUX2DLj4ARKoKOb1G0CpM",
            "displayName": {
              "text": "Central San Jose",
              "languageCode": "en"
            },
            "containment": "WITHIN"
          }
        ]
      }
    },
    /.../
  ]
}

Cobalah!

APIs Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda dapat memahami API dan opsi API.

  1. Pilih ikon API api di sisi kanan halaman.

  2. Edit parameter permintaan secara opsional.

  3. Pilih tombol Execute. Dalam dialog, pilih akun yang ingin Anda gunakan untuk membuat permintaan.

  4. Di panel APIs Explorer, pilih ikon layar penuh fullscreen untuk meluaskan jendela APIs Explorer.