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.

Selain parameter wajib, Text Search (New) mendukung penyempurnaan kueri menggunakan parameter opsional untuk mendapatkan hasil yang lebih baik.

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

Permintaan Text Search (Baru)

Permintaan Text Search (New) adalah permintaan POST HTTP dengan format berikut:

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

Teruskan semua parameter dalam 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)

Text Search (New) menampilkan objek JSON sebagai respons. Dalam respons:

  • Array places berisi semua tempat yang cocok.
  • Setiap tempat dalam array diwakili oleh objek Place. Objek Place berisi informasi mendetail tentang satu tempat.
  • FieldMask yang diteruskan dalam permintaan menentukan daftar kolom yang ditampilkan dalam objek Place.
  • Daftar tempat yang ditampilkan tidak dijamin konsisten untuk permintaan yang sama.

Objek JSON lengkap dalam bentuk:

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

Parameter yang diperlukan

  • 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 default kolom yang ditampilkan dalam respons. Jika Anda menghapus masker kolom, metode akan menampilkan error.

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

    Tentukan daftar jenis data tempat yang dipisahkan koma untuk 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.consumerAlert
      places.name*
      nextPageToken
      places.movedPlace
      places.movedPlaceId

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

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

    • 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.googleMapsTypeLabel
      places.googleMapsUri
      places.iconBackgroundColor
      places.iconMaskBaseUri
      places.location
      places.openingDate
      places.photos
      places.plusCode
      places.postalAddress
      places.primaryType
      places.primaryTypeDisplayName
      places.pureServiceAreaBusiness
      places.shortFormattedAddress
      places.searchUri
      places.subDestinations
      places.timeZone
      places.types
      places.utcOffsetMinutes
      places.viewport

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

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

    • 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.transitStation
      places.userRatingCount
      places.websiteUri

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

    • 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
      routingSummaries*
      places.servesBeer
      places.servesBreakfast
      places.servesBrunch
      places.servesCocktails
      places.servesCoffee
      places.servesDessert
      places.servesDinner
      places.servesLunch
      places.servesVegetarianFood
      places.servesWine
      places.takeout

      * Khusus Text Search dan Nearby Search

      Untuk mengetahui daftar lengkap kolom dan SKU terkaitnya, lihat Kolom Data Tempat (Baru).

  • textQuery

    String teks yang akan ditelusuri. Misalnya, "restoran", "123 Main Street", atau "Tempat terbaik untuk dikunjungi di San Francisco". API ini menampilkan kandidat hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.

    Text Search (Baru) tidak ditujukan untuk kueri yang ambigu, termasuk kueri berikut:

    Jenis kueri Contoh
    Terlalu banyak konsep atau batasan, seperti nama beberapa tempat, jalan, atau kota dalam satu kueri "Market Street San Francisco San Jose Airport"
    Elemen alamat pos tidak ditampilkan di Google Maps "C/O John Smith 123 Main Street"
    "P.O. Box 13 San Francisco"
    Nama bisnis, jaringan, atau kategori yang digabungkan dengan lokasi tempat entitas ini tidak tersedia "Tesco di dekat Dallas, Texas"
    Kueri ambigu dengan beberapa interpretasi "Pengembalian pengisi daya"
    Nama historis yang tidak lagi digunakan "Middlesex United Kingdom"
    Elemen atau niat non-geospasial "Berapa banyak perahu di Ventura Harbor?"
    Nama tidak resmi atau nama unik "The Jenga"
    "The Helter Skelter"
    Koordinat lintang dan bujur "37.422131,-122.084801"

Parameter opsional

  • includeFutureOpeningBusinesses

    Jika true, menampilkan bisnis yang diperkirakan akan dibuka pada masa mendatang. Nilai defaultnya adalah false.

    Untuk mengambil status bisnis, sertakan places.businessStatus dalam mask kolom permintaan Anda. Untuk mengambil perkiraan tanggal buka bisnis, sertakan places.openingDate dalam mask kolom permintaan Anda.

  • includedType

    Membias hasil ke tempat yang cocok dengan jenis yang ditentukan yang didefinisikan oleh Tabel A. Anda hanya dapat menentukan satu jenis. Contoh:

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

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

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

  • includePureServiceAreaBusinesses

    Jika ditetapkan ke true, respons akan menyertakan bisnis yang mengunjungi atau mengirimkan langsung ke pelanggan, tetapi tidak memiliki lokasi bisnis fisik. Jika ditetapkan ke false, API hanya akan 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 ditetapkan secara default ke en. Jika Anda menentukan kode bahasa yang tidak valid, API akan menampilkan error INVALID_ARGUMENT.
    • API ini berupaya sebaik mungkin untuk memberikan alamat yang dapat dibaca oleh pengguna dan penduduk setempat. Untuk mencapai tujuan tersebut, API ini menampilkan alamat jalan dalam bahasa lokal, yang ditransliterasikan ke skrip yang dapat dibaca oleh pengguna jika perlu, dengan mengamati bahasa pilihan. Semua alamat lainnya ditampilkan dalam bahasa pilihan. Komponen alamat semuanya 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 pengaruh kecil pada kumpulan hasil yang dipilih API untuk ditampilkan, dan urutan kemunculannya. 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 penentu wilayah tempat hasil harus berada, dan locationBias sebagai penentu wilayah tempat hasil kemungkinan akan berada di dalam atau di dekatnya, tetapi dapat berada di luar area tersebut.

    Tentukan wilayah sebagai Area Pandang persegi panjang atau sebagai lingkaran.

    • Lingkaran ditentukan oleh titik pusat dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Radius default-nya adalah 0,0. Contoh:

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

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

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

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

      Nilai rendah dan tinggi harus diisi, dan kotak yang diwakili tidak boleh kosong. Area pandang kosong akan menghasilkan error.

      Misalnya, area pandang 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 hanya untuk kueri kategoris, yang dapat menampilkan beberapa tempat (misalnya, "Restoran di Jakarta" atau "Pusat perbelanjaan"). Hasil di luar area yang ditentukan tidak akan ditampilkan.

    Tentukan wilayah sebagai Area Pandang persegi panjang. Untuk contoh penentuan Area Pandang, lihat deskripsi locationBias.

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

  • evOptions

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

    • connectorTypes

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

      • Untuk memfilter hasil untuk konektor tertentu yang didukung, tetapkan connectorTypes ke nilai tersebut. Misalnya, untuk menemukan konektor J1772 tipe 1, 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 jenis konektor apa pun 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 berdasarkan kecepatan pengisian daya EV minimum dalam kilowatt (kW). Setiap tempat dengan kecepatan pengisian daya kurang dari kecepatan pengisian daya minimum akan difilter. Misalnya, untuk menemukan pengisi daya EV dengan kecepatan pengisian daya minimal 10 kW, Anda dapat menetapkan parameter ini ke "10".

  • minRating

    Membatasi hasil hanya pada hasil yang rating pengguna rata-ratanya lebih besar dari atau sama dengan batas ini. Nilai harus antara 0,0 dan 5,0 (inklusif) dengan penambahan 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 tampilkan tempat yang sedang 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 di setiap halaman. Misalnya, menetapkan nilai pageSize 5 akan menampilkan hingga 5 hasil di halaman pertama. Jika kueri dapat menampilkan lebih banyak hasil, respons akan menyertakan nextPageToken yang dapat Anda teruskan dalam permintaan berikutnya untuk mengakses halaman berikutnya.

    Kolom ini menggantikan kolom maxResultCount yang tidak digunakan lagi. Jika Anda menentukan pageSize dan maxResultCount, API akan menggunakan pageSize dan mengabaikan maxResultCount.

  • pageToken

    Menentukan nextPageToken dari isi respons halaman sebelumnya.

  • priceLevels

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

    Tingkat harga dapat diperkirakan untuk tempat-tempat dengan jenis berikut:

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

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

    Contoh:

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

  • rankPreference

    Menentukan cara hasil diberi peringkat dalam respons berdasarkan jenis kueri:

    • Untuk kueri kategoris seperti "Restoran di Jakarta", RELEVANCE (peringkat hasil berdasarkan relevansi penelusuran) adalah defaultnya. Anda dapat menetapkan rankPreference ke RELEVANCE atau DISTANCE (memberi peringkat hasil berdasarkan jarak).
    • Untuk kueri non-kategori seperti "Mountain View, CA", sebaiknya biarkan rankPreference tidak ditetapkan.

  • regionCode

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

    Jika nama negara di kolom formattedAddress dalam respons cocok dengan regionCode, kode negara akan dihilangkan 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 ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  • strictTypeFiltering

    Digunakan dengan parameter includedType. Jika ditetapkan ke true, hanya tempat yang cocok dengan jenis yang ditentukan oleh includedType yang akan ditampilkan. Jika salah, yang merupakan 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 Text Search (New) 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 akan berbentuk:

{
  "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"
      }
    },
    ...
  ]
}

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'

Responsnya 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 berdasarkan tingkat harga

Gunakan opsi priceLevel untuk memfilter hasil ke restoran yang didefinisikan sebagai murah 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 dalam bentuk:

{
  "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 menyaring 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 penentu wilayah tempat hasil harus berada, dan locationBias sebagai penentu wilayah tempat hasil harus berada di dekatnya, tetapi dapat berada di luar area tersebut.

Membatasi area menggunakan locationRestriction

Gunakan parameter locationRestriction untuk membatasi hasil kueri ke region yang ditentukan. Dalam isi permintaan, tentukan nilai lintang dan 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'

Membias ke area menggunakan locationBias

Contoh berikut menunjukkan permintaan Text Search (Baru) untuk "makanan vegetarian" yang dibiaskan ke lokasi dalam radius 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 yang memiliki pengisi daya yang kompatibel dengan EV Anda.

Contoh berikut menunjukkan permintaan untuk konektor pengisi daya EV Tesla dan J1772 tipe 1 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"
          },
          ...
        ]
      }
    },
    {
      "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"
          }
        ]
      }
    },
    ...
  ]
}

Menelusuri bisnis jasa sistem panggilan

Gunakan parameter includePureServiceAreaBusinesses untuk menelusuri bisnis tanpa alamat layanan fisik (misalnya, layanan kebersihan 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"
      }
    },
    {
      "displayName": {
        "text": "Starboy Plumbing Inc.",
        "languageCode": "en"
      }
    },
    ...
  ]
}

Menentukan jumlah hasil yang akan ditampilkan per halaman

Gunakan parameter pageSize untuk menentukan jumlah hasil yang akan ditampilkan per halaman. Parameter nextPageToken dalam isi respons menyediakan 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"
    },
    ...
  ],
  "nextPageToken": "AeCrKXsZWzNVbPzO-MRWPu52jWO_Xx8aKwOQ69_Je3DxRpfdjClq8Ekwh3UcF2h2Jn75kL6PtWLGV4ecQri-GEUKN_OFpJkdVc-JL4Q"
}

Untuk mengakses halaman hasil berikutnya, gunakan pageToken untuk meneruskan nextPageToken dalam 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"
    },
    ...
  ],
  "nextPageToken": "AeCrKXvPd6uUy-oj96W2OaqEe2pUD8QTxOM8-sKfUcFsC9t2Wey5qivrKGoGSxcZnyc7RPmaFfAktslrKbUh31ZDTkL0upRmaxA7c_c"
}

Mendapatkan deskriptor alamat

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

Contoh berikut menunjukkan permintaan Text Search (New) untuk tempat-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

Responsnya mencakup tempat yang ditentukan dalam permintaan, daftar tempat terkenal di sekitar dan jaraknya dari tempat tersebut, serta daftar area dan hubungan cakupannya 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
          },
          ...
        ],
        "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"
          },
          ...
        ]
      }
    },
    ...
  ]
}

Menemukan bisnis yang akan dibuka pada masa mendatang

Contoh berikut menunjukkan permintaan Text Search (Baru) untuk bisnis yang akan dibuka di masa mendatang di New Meadows, Idaho:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.businessStatus,places.openingDate" \
-d '{
  "textQuery": "Roberts Greenhouse and Tree Farm",
  "includeFutureOpeningBusinesses": true,
  "maxResultCount": 20,
  "locationBias": {
    "circle": {
      "center": {"latitude": 44.9755100, "longitude": -116.2842180},
      "radius": 20
    }
  }
}' \
"https://places.googleapis.com/v1/places:searchText"

Responsnya mencakup bisnis yang akan dibuka pada masa mendatang, beserta status bisnis dan tanggal pembukaan yang diperkirakan:

{
  "places": [
    {
      "id": "ChIJp1-VoKWJplQRMz8g-7Wa3Do",
      "businessStatus": "FUTURE_OPENING",
      "displayName": {
        "text": "Roberts Greenhouse and Tree Farm",
        "languageCode": "en"
      },
      "openingDate": {
        "year": 2026,
        "month": 4,
        "day": 15
      }
    }
  ]
}

Mendapatkan informasi stasiun transportasi umum

Anda dapat menggunakan Text Search (Baru) untuk menemukan stasiun transportasi umum. Isi respons mencakup informasi tentang stasiun, termasuk nama stasiun, perusahaan transportasi umum yang berafiliasi, dan jalur transportasi umum yang melayani stasiun tersebut. Selain itu, responsnya menyertakan ikon kendaraan dan warna yang dapat Anda gunakan untuk menampilkan informasi stasiun transportasi umum.

Contoh berikut menunjukkan permintaan untuk "Grand Central Station":

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.transitStation" \
-d '{
  "textQuery": "Grand Central Station"
}' \
"https://places.googleapis.com/v1/places:searchText"

Isi respons mencakup informasi tentang setiap stasiun dalam radius, jalur yang dilayani oleh stasiun, pemberitahuan yang dikeluarkan oleh perusahaan transportasi umum di perhentian tersebut, dan informasi keberangkatan:

{
  "places": [
    {
      "id": "ChIJhRwB-yFawokRi0AhGH87UTc",
      "displayName": {
        "text": "Grand Central",
        "languageCode": "en"
      },
      "transitStation": {
        "displayName": {
          "text": "Grand Central",
          "languageCode": "en"
        },
        "agencies": [
          {
            "displayName": {
              "text": "Metro-North Railroad",
              "languageCode": "en"
            },
            "url": "http://www.mta.info/mnr",
            "lines": [
              {
                "id": "ChIJOXpD29y2wokRryDO0CocwK0",
                "vehicleType": "HEAVY_RAIL",
                "displayName": {
                  "text": "Harlem",
                  "languageCode": "en"
                },
                "textColor": "#FFFFFF",
                "backgroundColor": "#0061AA",
                "vehicleIcon": {
                  "url": "https://maps.gstatic.com/mapfiles/transit/iw2/svg/rail2.svg"
                },
                "alerts": [
                  {
                    "effect": "OTHER",
                    "texts": [
                      {
                        "headline": {
                          "text": "Information",
                          "languageCode": "en"
                        },
                        "summary": {
                          "text": "Temporary platforms are in place at Botanical Garden, Williams Bridge, and Woodlawn for northbound travel. Build in extra travel time to reach the platform.",
                          "languageCode": "en"
                        },
                        "fullDescription": {
                          "text": "What's Happening? We are renovating some Harlem Line stations in the Bronx. Learn more about the project here.",
                          "languageCode": "en"
                        }
                      }
                    ],
                    "detailsUrls": [
                      {
                        "url": "https://new.mta.info/"
                      }
                    ],
                    "cause": "OTHER_CAUSE",
                    "startTime": "2026-04-16T04:00:00Z",
                    "endTime": "2026-12-01T04:45:00Z",
                    "attribution": {
                      "link": {
                        "text": "new.mta.info",
                        "url": "https://new.mta.info/"
                      }
                    },
                    "createTime": "2026-05-15T22:39:30Z",
                    "severityLevel": "INFO"
                  }
                ]
              },
              ...
            ]
          },
          ...
        ]
        "stops": [
          {
            "id": "ChIJOfdrigFZwokRJPllLwfPrJY",
            "location": {
              "latitude": 40.752823,
              "longitude": -73.977195999999992
            },
            "wheelchairAccessibleEntrance": true
          }
        ],
        "departureBoards": [
          {
            "displayType": "TIME_CENTRIC",
            "rows": [
              {
                "departures": [
                  {
                    "timedDeparture": {
                      "scheduledTime": "2026-05-15T22:42:00Z",
                      "timingType": "SCHEDULED",
                      "predictedTime": "2026-05-15T22:42:00Z",
                      "updateTime": "2026-05-15T22:38:50Z"
                    },
                    "originallyScheduledStopId": "ChIJOfdrigFZwokRJPllLwfPrJY",
                    "lineId": "ChIJAfBuQhwg6IkRYnFpClHxFrM"
                  }
                ]
              },
              ...
            ]
          }
        ]
      }
    },
    {
      "id": "ChIJ_4EAi-pZwokRWe5T1JmmWmc",
      "displayName": {
        "text": "Grand Central Station",
        "languageCode": "en"
      }
    }
  ]
}

Mendapatkan pintu masuk dan titik navigasi

Anda dapat meminta pintu masuk dan titik navigasi untuk suatu tujuan. Pintu masuk menentukan titik masuk dan keluar untuk suatu tempat (misalnya, gerbang yang berbeda di bandara atau mal). Titik navigasi menentukan lokasi di tepi jalan tempat navigasi harus berakhir, yang berguna untuk mengarahkan pengguna ke sisi jalan yang benar atau titik penurunan tertentu.

Titik navigasi menampilkan navigationPointToken. Anda dapat meneruskan token ini ke Navigation SDK (tersedia untuk Android atau iOS) atau Routes API untuk memandu pengemudi ke lokasi spesifik tersebut. Untuk mengetahui informasi selengkapnya, lihat Token titik navigasi.

Contoh berikut menunjukkan permintaan Text Search (New) untuk "San Francisco International Airport" yang menyertakan entrances dan navigationPoints dalam mask kolom:

curl -X POST \
-H "Content-Type: application/json" \
-H "X-Goog-Api-Key: API_KEY" \
-H "X-Goog-FieldMask: places.id,places.displayName,places.entrances,places.navigationPoints" \
-d '{
  "textQuery": "San Francisco International Airport",
  "pageSize": 1
}' \
"https://places.googleapis.com/v1/places:searchText"

Responsnya mencakup pintu masuk dan titik navigasi untuk tempat tersebut:

{
  "places": [
    {
      "id": "ChIJVVVVVYx3j4ARP-3NGldc8qQ",
      "displayName": {
        "text": "San Francisco International Airport",
        "languageCode": "en"
      },
      "entrances": [
        {
          "location": {
            "latitude": 37.6172154,
            "longitude": -122.3839724
          }
        },
        {
          "location": {
            "latitude": 37.6174073,
            "longitude": -122.384196
          }
        },
        ...
      ],
      "navigationPoints": [
        {
          "navigationPointToken": "ChIJoioBjMLOQkAR0A3yH_eYXsA...",
          "displayName": {
            "text": "International Terminal Departures Level",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6153121,
            "longitude": -122.3900833
          },
          "travelModes": ["WALK"]
        },
        {
          "navigationPointToken": "ChIJy5JKws_OQkAROx0jNN2YXsA...",
          "displayName": {
            "text": "Domestic Garage - SFO Short Term Parking",
            "languageCode": "en"
          },
          "location": {
            "latitude": 37.6157153,
            "longitude": -122.3885012
          },
          "travelModes": ["DRIVE", "WALK"],
          "usages": ["PARKING"]
        },
        ...
      ]
    }
  ]
}

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 jika perlu.

  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.