Nearby Search (Baru) mengambil satu atau beberapa jenis tempat, dan menampilkan daftar tempat yang cocok dalam area tertentu. Mask kolom yang menentukan satu atau beberapa jenis data tidak diperlukan. Nearby Search (Baru) hanya mendukung permintaan POST.
API Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat membiasakan diri dengan API dan Opsi API:
Cobalah!Coba interaktif demo untuk melihat hasil Nearby Search (Baru) yang ditampilkan di peta.
Permintaan Nearby Search (Baru)
Permintaan Nearby Search (Baru) adalah permintaan HTTP POST ke URL di bentuk:
https://places.googleapis.com/v1/places:searchNearby
Teruskan semua parameter di isi permintaan JSON atau di header sebagai bagian dari permintaan POST. Contoh:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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" \ https://places.googleapis.com/v1/places:searchNearby
Respons Nearby Search (Baru)
Nearby Search (Baru) menampilkan Objek JSON sebagai respons. Dalam respons:
- Array
places
berisi semua tempat yang cocok. - Setiap tempat dalam {i>array<i} diwakili oleh elemen
Place
. ObjekPlace
berisi informasi mendetail tentang satu saat ini. - FieldMask yang diteruskan dalam permintaan menentukan daftar kolom
yang ditampilkan dalam objek
Place
.
Objek JSON lengkap tersedia dalam bentuk:
{ "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
ataufields
, atau dengan menggunakan header HTTPX-Goog-FieldMask
. Tidak ada daftar default untuk kolom yang ditampilkan dalam respons. Jika Anda menghilangkan mask kolom, metode akan menampilkan error.Penyamaran kolom adalah praktik desain yang baik untuk memastikan bahwa Anda tidak meminta data yang tidak perlu, yang membantu menghindari waktu pemrosesan yang tidak perlu dan biaya penagihan.
Tentukan daftar yang dipisahkan koma untuk jenis data tempat 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 Nearby Search (Basic):
places.accessibilityOptions
,places.addressComponents
,places.adrFormatAddress
,places.attributions
,places.businessStatus
,places.displayName
,places.formattedAddress
,places.googleMapsUri
,places.iconBackgroundColor
,places.iconMaskBaseUri
,places.id
,places.location
,places.name
*,places.photos
,places.plusCode
,places.primaryType
,places.primaryTypeDisplayName
,places.shortFormattedAddress
,places.subDestinations
,places.types
,places.utcOffsetMinutes
,places.viewport
* Kolomplaces.name
berisi nama resource tempat dalam bentuk:places/PLACE_ID
. Gunakanplaces.displayName
untuk mengakses nama tekstual tempat tersebut.Kolom berikut memicu SKU Nearby Search (Advanced):
places.currentOpeningHours
,places.currentSecondaryOpeningHours
,places.internationalPhoneNumber
,places.nationalPhoneNumber
,places.priceLevel
,places.rating
,places.regularOpeningHours
,places.regularSecondaryOpeningHours
,places.userRatingCount
,places.websiteUri
Kolom berikut memicu SKU (Preferred) Nearby Search:
places.allowsDogs
,places.curbsidePickup
,places.delivery
,places.dineIn
,places.editorialSummary
,places.evChargeOptions
,places.fuelOptions
,places.goodForChildren
,places.goodForGroups
,places.goodForWatchingSports
,places.liveMusic
,places.menuForChildren
,places.parkingOptions
,places.paymentOptions
,places.outdoorSeating
,places.reservable
,places.restroom
,places.reviews
,places.servesBeer
,places.servesBreakfast
,places.servesBrunch
,places.servesCocktails
,places.servesCoffee
,places.servesDessert
,places.servesDinner
,places.servesLunch
,places.servesVegetarianFood
,places.servesWine
,places.takeout
-
locationRestriction
Wilayah yang akan ditelusuri ditentukan sebagai lingkaran, yang didefinisikan berdasarkan titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Radius default-nya adalah 0.0. Anda harus tetapkan ke nilai yang lebih besar dari 0,0 dalam permintaan Anda.
Contoh:
"locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 500.0 } }
Parameter opsional
-
includeTypes/excludedTypes, disertakanPrimaryTypes/excludedPrimaryTypes
Memungkinkan Anda menentukan daftar jenis dari jenis Tabel A digunakan untuk memfilter hasil penelusuran. Maksimal 50 jenis dapat ditentukan dalam setiap kategori pembatasan jenis.
Sebuah tempat hanya dapat memiliki satu jenis utama dari beberapa jenis Tabel A yang terkait dengan anotasi. Misalnya, tipe utama mungkin
"mexican_restaurant"
atau"steak_house"
. GunakanincludedPrimaryTypes
danexcludedPrimaryTypes
untuk memfilter hasil tipe utama tempat.Tempat juga dapat memiliki beberapa nilai jenis dari jenis Tabel A yang terkait dengannya. Misalnya, restoran mungkin memiliki jenis berikut:
"seafood_restaurant"
,"restaurant"
,"food"
,"point_of_interest"
,"establishment"
. GunakanincludedTypes
danexcludedTypes
untuk memfilter hasil pada daftar jenis yang terkait dengan di suatu tempat.Saat Anda menentukan jenis utama umum, seperti
"restaurant"
atau"hotel"
, respons dapat berisi tempat dengan jenis utama yang lebih spesifik daripada yang ditentukan. Misalnya, Anda menentukan untuk menyertakan jenis utama"restaurant"
. Responsnya kemudian bisa berisi tempat dengan tipe utama"restaurant"
, tetapi responsnya juga dapat berisi tempat dengan jenis utama, seperti"chinese_restaurant"
atau"seafood_restaurant"
.Jika penelusuran ditentukan dengan beberapa pembatasan jenis, hanya tempat yang memenuhi semua batasan akan ditampilkan. Misalnya, jika Anda menentukan
{"includedTypes": ["restaurant"], "excludedPrimaryTypes": ["steak_house"]}
, tempat yang ditampilkan menyediakan layanan terkait"restaurant"
, tetapi tidak beroperasi secara utama sebagai"steak_house"
.includedTypes
Daftar yang dipisahkan koma untuk jenis tempat dari Tabel A yang akan ditelusuri. Jika parameter ini dihilangkan, semua jenis tempat akan ditampilkan.
excludedTypes
Daftar jenis tempat yang dipisahkan koma dari Tabel A yang akan dikecualikan dari cari.
Jika Anda menentukan
includedTypes
( seperti"school"
) danexcludedTypes
(seperti"primary_school"
) dalam permintaan, lalu menyertakan tempat yang dikategorikan sebagai"school"
, tetapi bukan sebagai"primary_school"
. Respons mencakup tempat yang cocok dengan setidaknya salah satu dariincludedTypes
dan tidak satu pun dariexcludedTypes
.Jika ada jenis yang bertentangan, seperti jenis yang muncul di kedua
includedTypes
danexcludedTypes
, errorINVALID_REQUEST
akan ditampilkan.includedPrimaryTypes
Daftar yang dipisahkan koma berisi jenis tempat utama dari Tabel A yang akan disertakan dalam penelusuran.
excludedPrimaryTypes
Daftar jenis tempat utama yang dipisahkan koma dari Tabel A yang akan dikecualikan dari penelusuran.
Jika ada jenis utama yang bertentangan, seperti jenis yang muncul di kedua
includedPrimaryTypes
danexcludedPrimaryTypes
,INVALID_ARGUMENT
error yang ditampilkan. -
languageCode
Bahasa yang digunakan untuk menampilkan hasil.
- Lihat daftar bahasa yang didukung. Sering menggunakan Google memperbarui bahasa yang didukung, sehingga daftar ini tidak lengkap.
- Jika
languageCode
tidak diberikan, API akan ditetapkan secara default keen
. Jika Anda menetapkan kode bahasa yang tidak valid, API akan menampilkanINVALID_ARGUMENT
{i>error<i}. - API ini melakukan yang terbaik untuk menyediakan alamat yang mudah dibaca oleh pengguna dan lokal. Untuk mencapai tujuan itu, {i>router<i} mengembalikan alamat dalam bahasa lokal, ditransliterasi ke skrip yang dapat dibaca oleh pengguna jika perlu, dengan memperhatikan di bahasa target. Semua alamat lain dikembalikan dalam bahasa yang dipilih. Komponen alamat adalah semua dikembalikan dalam bahasa yang sama, yang dipilih dari komponen pertama.
- Jika nama tidak tersedia dalam bahasa yang dipilih, API menggunakan bahasa terdekat yang sesuai.
- Bahasa yang dipilih memiliki pengaruh kecil pada rangkaian hasil yang dipilih API yang dikembalikan, dan urutan pengembaliannya. Geocoder menafsirkan singkatan berbeda-beda bergantung pada bahasa, seperti singkatan untuk jenis jalan, atau sinonim yang mungkin valid dalam satu bahasa tetapi tidak dalam bahasa lain.
-
maxResultCount
Menentukan jumlah maksimum hasil tempat yang akan ditampilkan. Harus antara 1 dan 20 (default) inklusif.
-
rankPreference
Jenis peringkat yang akan digunakan. Jika parameter ini dihilangkan, hasil akan diurutkan berdasarkan popularitas. Mungkin berupa salah satu dari hal berikut:
POPULARITY
(default) Mengurutkan hasil berdasarkan popularitasnya.DISTANCE
Mengurutkan hasil dalam urutan menaik berdasarkan jaraknya dari lokasi yang ditentukan.
-
regionCode
Kode wilayah yang digunakan untuk memformat respons, yang ditetapkan sebagai kode CLDR dua karakter. Tidak ada nilai default.
Jika nama negara kolom
formattedAddress
dalam respons cocok denganregionCode
, kode negara dihilangkan dariformattedAddress
. Parameter ini tidak berpengaruh padaadrFormatAddress
, yang selalu menyertakan negara nama, atau padashortFormattedAddress
, 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 "Inggris Raya dan Irlandia Utara"). Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.
Contoh Nearby Search (Baru)
Menemukan tempat yang sejenis
Contoh berikut menampilkan permintaan Nearby Search (Baru) untuk tampilan
nama semua restoran dalam radius 500 meter, yang ditentukan dengan circle
:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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" \ https://places.googleapis.com/v1/places:searchNearby
Perhatikan bahwa header X-Goog-FieldMask
menentukan bahwa respons
berisi kolom data berikut: places.displayName
.
Respons
kemudian dalam bentuk:
{ "places": [ { "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, { "displayName": { "text": "Harborview Restaurant & Bar", "languageCode": "en" } }, ... }
Tambahkan lebih banyak jenis data ke mask kolom untuk menampilkan informasi tambahan.
Misalnya, tambahkan places.formattedAddress,places.types,places.websiteUri
untuk menyertakan
alamat, jenis, dan alamat Web restoran dalam respons:
curl -X POST -d '{ "includedTypes": ["restaurant"], "maxResultCount": 10, "locationRestriction": { "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,places.types,places.websiteUri" \ https://places.googleapis.com/v1/places:searchNearby
Respons kini dalam bentuk:
{ "places": [ { "types": [ "seafood_restaurant", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "PIER 1 1/2 The Embarcadero N, San Francisco, CA 94105, USA", "websiteUri": "http://lamarsf.com/", "displayName": { "text": "La Mar Cocina Peruana", "languageCode": "en" } }, { "types": [ "greek_restaurant", "meal_takeaway", "restaurant", "food", "point_of_interest", "establishment" ], "formattedAddress": "200 Jackson St, San Francisco, CA 94111, USA", "websiteUri": "https://kokkari.com/", "displayName": { "text": "Kokkari Estiatorio", "languageCode": "en" } }, ... }
Menemukan beberapa jenis tempat
Contoh berikut menampilkan permintaan Nearby Search (Baru) untuk
nama tampilan semua minimarket dan toko minuman keras dalam radius 1.000 meter dari
circle
yang ditentukan:
curl -X POST -d '{ "includedTypes": ["liquor_store", "convenience_store"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName,places.primaryType,places.types" \ https://places.googleapis.com/v1/places:searchNearby
places.primaryType
dan places.types
ke mask kolom
sehingga responsnya menyertakan informasi jenis tentang setiap tempat, sehingga lebih mudah untuk memilih
tempat yang sesuai dari hasil tersebut.
Mengecualikan jenis tempat dari penelusuran
Contoh berikut menampilkan permintaan Nearby Search (Baru) untuk semua tempat
dari jenis "school"
, tidak termasuk semua tempat dari jenis "primary_school"
, memberi peringkat hasil
menurut jarak:
curl -X POST -d '{ "includedTypes": ["school"], "excludedTypes": ["primary_school"], "maxResultCount": 10, "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } }, "rankPreference": "DISTANCE" }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Menelusuri semua tempat di dekat suatu area, peringkat berdasarkan jarak
Contoh berikut menampilkan permintaan Nearby Search (Baru) untuk tempat
di dekat titik tertentu di
pusat kota San Francisco. Dalam contoh ini, Anda menyertakan rankPreference
untuk memeringkatkan hasil menurut jarak:
curl -X POST -d '{ "maxResultCount": 10, "rankPreference": "DISTANCE", "locationRestriction": { "circle": { "center": { "latitude": 37.7937, "longitude": -122.3965 }, "radius": 1000.0 } } }' \ -H 'Content-Type: application/json' -H "X-Goog-Api-Key: API_KEY" \ -H "X-Goog-FieldMask: places.displayName" \ https://places.googleapis.com/v1/places:searchNearby
Cobalah!
API Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda bisa membiasakan diri dengan API dan opsi API.
- Pilih ikon API,
, di sisi kanan halaman.
- (Opsional) Memperluas Tampilkan parameter standar dan atur
parameter
fields
ke mask kolom. - Jika ingin, edit Isi permintaan.
- Pilih tombol Execute. Di jendela pop-up, pilih akun yang ingin digunakan untuk membuat permintaan.
Di panel API Explorer, pilih ikon luaskan,
, untuk meluaskan jendela API Explorer.