Ringkasan
Fungsi di Library Places, Maps JavaScript API memungkinkan aplikasi Anda menelusuri tempat (didefinisikan dalam API ini sebagai tempat usaha, lokasi geografis, atau lokasi menarik terkemuka) yang terdapat dalam area yang ditentukan, seperti batas peta, atau di sekitar titik tetap.
Places API menawarkan fitur pelengkapan otomatis yang dapat Anda gunakan untuk memberikan aplikasi Anda perilaku prediksi penelusuran pada kolom penelusuran Google Maps. Saat pengguna mulai mengetik alamat, pelengkapan otomatis akan mengisikan sisanya. Untuk mengetahui informasi selengkapnya, lihat dokumentasi pelengkapan otomatis.
Memulai
Jika belum memahami Maps JavaScript API atau JavaScript, sebaiknya Anda meninjau JavaScript dan Mendapatkan Kunci API sebelum memulai.
Mengaktifkan API
Sebelum menggunakan Library Places di Maps JavaScript API, pastikan terlebih dahulu Places API diaktifkan di Konsol Google Cloud, dalam project yang sama yang Anda siapkan untuk Maps JavaScript API.
Untuk menampilkan daftar API yang telah diaktifkan:
- Buka Google Cloud Console.
- Klik tombol Select a project, lalu pilih project yang sama dengan yang Anda siapkan untuk Maps JavaScript API dan klik Open.
- Dari daftar API di Dashboard, cari Places API.
- Jika Anda melihat Places API dalam daftar, berarti API tersebut sudah diaktifkan. Jika API tidak tercantum,
aktifkan:
- Di bagian atas halaman, pilih ENABLE APIS AND SERVICES untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
- Telusuri Places API, lalu pilih dari daftar hasil.
- Pilih ENABLE. Setelah proses ini selesai, Places API akan muncul dalam daftar API di Dashboard.
Memuat library
Layanan Places adalah library mandiri, yang terpisah dari kode
Maps JavaScript API utama. Untuk menggunakan fungsi yang ada dalam library ini, Anda harus memuatnya terlebih dahulu menggunakan parameter libraries
di URL bootstrap Maps API:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Lihat Ringkasan Library untuk informasi selengkapnya.
Menambahkan Places API ke daftar pembatasan API untuk kunci API
Menerapkan pembatasan API ke kunci Anda akan membatasi penggunaan kunci API untuk satu atau beberapa API atau SDK. Permintaan ke API atau SDK terkait kunci API akan diproses. Permintaan ke API atau SDK yang tidak terkait dengan kunci API akan gagal. Untuk membatasi kunci API yang akan digunakan dengan Library Places, Maps JavaScript API:- Buka Google Cloud Console.
- Klik drop-down project dan pilih project yang berisi kunci API yang ingin Anda amankan.
- Klik tombol menu
lalu pilih Google Maps Platform > Credentials.
- Di halaman Credentials, klik nama kunci API yang ingin Anda amankan.
- Di halaman Restrict and rename API key, tetapkan pembatasan:
- Pembatasan API
- Pilih Restrict key.
- Klik Select APIs lalu pilih Maps JavaScript API dan Places API.
(Jika salah satu API tidak tercantum, Anda harus mengaktifkannya.)
- Klik SAVE.
Kebijakan dan batas penggunaan
Kuota
Library Places berbagi kuota penggunaan dengan Places API seperti yang dijelaskan dalam dokumentasi Batas Penggunaan untuk Places API.
Kebijakan
Penggunaan Places Library, Maps JavaScript API harus sesuai dengan kebijakan yang dijelaskan untuk Places API.
Place Search
Dengan layanan Places, Anda dapat melakukan jenis penelusuran berikut:
- Find Place from Query menampilkan tempat berdasarkan kueri teks (misalnya, nama atau alamat tempat).
- Find Place from Phone Number menampilkan tempat berdasarkan nomor telepon.
- Nearby Search menampilkan daftar tempat-tempat terdekat berdasarkan lokasi pengguna.
- Text Search menampilkan daftar tempat-tempat terdekat berdasarkan string penelusuran, misalnya, "Pizza".
- Permintaan Place Details menampilkan informasi lebih mendetail tentang tempat tertentu, termasuk ulasan pengguna.
Informasi yang ditampilkan dapat mencakup tempat usaha — seperti restoran, toko, dan kantor — serta hasil 'geocode', yang menunjukkan alamat, area politik seperti kota kecil dan kota besar, serta lokasi menarik lainnya.
Permintaan Find Place
Permintaan Find Place memungkinkan Anda menelusuri tempat dengan kueri teks atau nomor telepon. Ada dua jenis permintaan Find Place:
Find Place from Query
Find Place from Query menggunakan input teks dan menampilkan tempat. Input dapat berupa jenis data Tempat apa pun, misalnya nama atau alamat bisnis. Untuk membuat
permintaan Find Place from Query, panggil metode
findPlaceFromQuery()
PlacesService
,
yang menggunakan parameter berikut:
query
(wajib) String teks yang digunakan untuk menelusuri, misalnya: "restaurant" atau "123 Main Street". String ini harus berupa nama tempat, alamat, atau kategori tempat usaha. Jenis input lainnya dapat menghasilkan error dan tidak dijamin akan menampilkan hasil yang valid. Places API akan menampilkan kandidat hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.fields
(wajib) Satu atau beberapa kolom yang menentukan jenis data Tempat yang akan ditampilkan.locationBias
(opsional) Koordinat yang menentukan area yang akan ditelusuri. Koordinat ini bisa berupa salah satu dari yang berikut:- Kumpulan koordinat lintang/bujur yang ditentukan sebagai LatLngLiteral atau objek LatLng
- Batas persegi panjang (dua pasangan lintang/bujur, atau objek LatLngBounds)
- Radius (dalam meter) yang berpusat pada lintang/bujur
Anda juga harus meneruskan metode callback ke findPlaceFromQuery()
, untuk menangani objek hasil dan respons
google.maps.places.PlacesServiceStatus
.
Contoh berikut menunjukkan panggilan ke findPlaceFromQuery()
, yang menelusuri "Museum of Contemporary Art Australia", dan menyertakan kolom name
dan geometry
.
var map; var service; var infowindow; function initMap() { var sydney = new google.maps.LatLng(-33.867, 151.195); infowindow = new google.maps.InfoWindow(); map = new google.maps.Map( document.getElementById('map'), {center: sydney, zoom: 15}); var request = { query: 'Museum of Contemporary Art Australia', fields: ['name', 'geometry'], }; var service = new google.maps.places.PlacesService(map); service.findPlaceFromQuery(request, function(results, status) { if (status === google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } map.setCenter(results[0].geometry.location); } }); }Lihat contoh
Find Place from Phone Number
Find Place from Phone Number menggunakan nomor telepon dan menampilkan tempat. Untuk
membuat permintaan Find Place from Phone Number, panggil
metode findPlaceFromPhoneNumber()
PlacesService
, yang menggunakan parameter berikut:
phoneNumber
(wajib) Nomor telepon, dalam format E.164.fields
(wajib) Satu atau beberapa kolom yang menentukan jenis data Tempat yang akan ditampilkan.locationBias
(opsional) Koordinat yang menentukan area yang akan ditelusuri. Koordinat ini bisa berupa salah satu dari yang berikut:- Kumpulan koordinat lintang/bujur yang ditentukan sebagai LatLngLiteral atau objek LatLng
- Batas persegi panjang (empat titik lintang/bujur atau objek LatLngBounds)
- Radius (dalam meter) yang berpusat pada lintang/bujur
Anda juga harus meneruskan metode callback ke findPlaceFromPhoneNumber()
, untuk menangani objek hasil dan respons
google.maps.places.PlacesServiceStatus
.
Kolom (metode Find Place)
Gunakan parameter fields
untuk menentukan array jenis data tempat yang akan ditampilkan.
Contoh: fields: ['formatted_address', 'opening_hours', 'geometry']
.
Gunakan titik saat menentukan nilai gabungan. Contoh: opening_hours.weekday_text
.
Kolom sesuai dengan hasil Place Search, dan dibagi
menjadi tiga kategori penagihan: Basic, Contact, dan Atmosphere. Kolom Basic
ditagih dengan tarif dasar dan tidak dikenai biaya tambahan. Kolom Contact dan Atmosphere ditagih dengan tarif lebih tinggi. Lihat sheet harga
untuk mengetahui informasi selengkapnya. Atribusi (html_attributions
) selalu ditampilkan dengan setiap panggilan, terlepas dari apakah kolom telah diminta
atau tidak.
Basic
Kategori Basic mencakup kolom berikut:
business_status
, formatted_address
, geometry
,
icon
,icon_mask_base_uri
, icon_background_color
,
name
, permanently_closed
(tidak digunakan lagi),
photos
, place_id
, plus_code
, types
Contact
Kategori Contact mencakup kolom berikut:opening_hours
(tidak digunakan lagi di Places Library, Maps JavaScript API. Gunakan permintaan Place Details untuk mendapatkan hasil
opening_hours
).
Atmosphere
Kategori Atmosphere mencakup kolom berikut:price_level
, rating
, user_ratings_total
Metode findPlaceFromQuery()
dan findPlaceFromPhoneNumber()
masing-masing menggunakan kumpulan kolom yang sama, dan dapat menampilkan kolom yang sama dalam responsnya masing-masing.
Menetapkan bias lokasi (metode Find Place)
Gunakan parameter locationBias
untuk membuat Find Place mendukung hasil di area tertentu. Anda dapat menetapkan locationBias
dengan cara berikut:
Membiaskan hasil ke area tertentu:
locationBias: {lat: 37.402105, lng: -122.081974}
Menentukan area persegi panjang yang akan ditelusuri:
locationBias: {north: 37.41, south: 37.40, east: -122.08, west: -122.09}
Anda juga dapat menggunakan LatLngBounds.
Menentukan radius yang akan ditelusuri (dalam meter), yang berpusat pada area tertentu:
locationBias: {radius: 100, center: {lat: 37.402105, lng: -122.081974}}
Permintaan Nearby Search
Nearby Search memungkinkan Anda menelusuri tempat dalam area yang ditetapkan dengan kata kunci atau jenis. Nearby Search harus selalu menyertakan lokasi, yang bisa ditetapkan dalam salah satu dari dua cara berikut:
-
LatLngBounds
. - area melingkar yang didefinisikan sebagai kombinasi dari properti
location
— yang menentukan pusat lingkaran sebagai objekLatLng
— dan radius, yang diukur dalam meter.
Penelusuran Places Nearby dimulai dengan panggilan ke metode nearbySearch()
PlacesService
, yang akan menampilkan array
PlaceResult
. Perhatikan bahwa metode nearbySearch()
menggantikan metode search()
mulai versi 3.9.
service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback);
Metode ini mengambil permintaan dengan kolom berikut:
- Salah satu dari:
bounds
, yang harus berupa Objekgoogle.maps.LatLngBounds
yang menentukan persegi panjang area penelusuran. Jarak diagonal maksimum yang didukung untuk batas luasnya sekitar 100.000 meter.location
danradius
; yang pertama menggunakan objekgoogle.maps.LatLng
, dan yang kedua menggunakan bilangan bulat sederhana yang menampilkan radius lingkaran dalam meter. Maksimum radius yang diizinkan adalah 50.000 meter. Perhatikan bahwa saatrankBy
ditetapkan ke DISTANCE, Anda harus menentukanlocation
, tetapi Anda tidak dapat menentukanradius
ataubounds
.
keyword
(opsional) — Istilah yang akan dicocokkan dengan semua kolom yang tersedia, termasuk, tetapi tidak terbatas pada nama, jenis, dan alamat, serta ulasan pelanggan dan konten pihak ketiga lainnya.minPriceLevel
danmaxPriceLevel
(opsional) — Membatasi hasil hanya ke tempat yang berada dalam rentang yang ditentukan. Nilai yang valid berkisar antara 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.name
Tidak digunakan lagi. Setara dengankeyword
. Nilai di kolom ini digabungkan dengan nilai di kolomkeyword
dan diteruskan sebagai bagian dari string penelusuran yang sama.openNow
(opsional) — Nilai boolean, yang menunjukkan bahwa layanan Places hanya boleh menampilkan tempat yang sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan ditampilkan jika Anda menyertakan parameter ini dalam kueri. MenetapkanopenNow
kefalse
tidak akan berpengaruh.rankBy
(opsional) — Menentukan urutan daftar hasil. Nilainya dapat berupa:google.maps.places.RankBy.PROMINENCE
(default). Opsi ini menyortir hasil menurut tingkat kepentingannya. Peringkat akan mengutamakan tempat terkemuka dalam radius yang telah ditentukan dibandingkan tempat terdekat yang cocok tetapi kurang terkemuka. Tempat terkemuka bisa dipengaruhi oleh peringkat suatu tempat dalam indeks Google, popularitas global, dan faktor lainnya. Jikagoogle.maps.places.RankBy.PROMINENCE
ditentukan, parameterradius
wajib diisi.google.maps.places.RankBy.DISTANCE
. Opsi ini mengurutkan hasil dalam urutan menaik berdasarkan jaraknya darilocation
yang telah ditentukan (wajib). Perhatikan bahwa Anda tidak dapat menentukanbounds
dan/atauradius
kustom jika Anda menentukanRankBy.DISTANCE
. Saat Anda menentukanRankBy.DISTANCE
, satu atau beberapakeyword
,name
, atautype
diperlukan.
type
— Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan. Hanya satu jenis yang dapat ditentukan (jika lebih dari satu jenis disediakan, semua jenis setelah entri pertama akan diabaikan). Lihat daftar jenis yang didukung.
Anda juga harus meneruskan metode callback ke nearbySearch()
untuk menangani objek hasil dan respons google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', type: ['restaurant'] }; service = new google.maps.places.PlacesService(map); service.nearbySearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { createMarker(results[i]); } } }
Permintaan Text Search
Layanan Google Places Text Search adalah layanan web yang menampilkan informasi tentang serangkaian tempat berdasarkan suatu string — misalnya "pizza di Bandung" atau "toko sepatu dekat Solo". Layanan ini merespons dengan daftar tempat yang cocok dengan string teks dan bias lokasi yang telah ditetapkan. Respons penelusuran akan menyertakan daftar tempat. Anda bisa mengirim permintaan Place Details untuk informasi selengkapnya tentang tempat dalam respons tersebut.
Text Search dimulai dengan panggilan ke metode textSearch()
dari PlacesService
.
service = new google.maps.places.PlacesService(map); service.textSearch(request, callback);
Metode ini mengambil permintaan dengan kolom berikut:
query
(wajib) String teks yang digunakan untuk menelusuri tempat, misalnya: "restaurant" atau "123 Main Street". String ini harus berupa nama tempat, alamat, atau kategori tempat usaha. Jenis input lainnya dapat menghasilkan error dan tidak dijamin akan menampilkan hasil yang valid. Layanan Places akan menampilkan bakal hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat. Parameter ini menjadi opsional jika parametertype
juga digunakan dalam permintaan penelusuran.- Opsional:
openNow
— Nilai boolean, yang menunjukkan bahwa layanan Places hanya boleh menampilkan tempat yang sedang buka pada saat kueri dikirim. Tempat yang tidak menetapkan jam buka dalam database Google Places tidak akan ditampilkan jika Anda menyertakan parameter ini dalam kueri. MenetapkanopenNow
kefalse
tidak akan berpengaruh.minPriceLevel
danmaxPriceLevel
— Membatasi hasil hanya ke tempat yang berada dalam tingkat harga yang ditentukan. Nilai yang valid berkisar dari 0 (paling terjangkau) hingga 4 (paling mahal), inklusif.- Salah satu dari:
bounds
, yang harus berupa Objekgoogle.maps.LatLngBounds
yang menentukan persegi panjang area penelusuran. Jarak diagonal maksimum yang didukung untuk batas luasnya sekitar 100.000 meter.location
danradius
— Anda dapat membiaskan hasil ke lingkaran yang ditentukan dengan meneruskan parameterlocation
danradius
. Cara ini akan menginstruksikan layanan Places agar memprioritaskan untuk menampilkan hasil dalam lingkaran tersebut. Hasil di luar area yang didefinisikan mungkin tetap ditampilkan. Lokasi menggunakan objekgoogle.maps.LatLng
, dan radius menggunakan bilangan bulat sederhana, yang menampilkan radius lingkaran dalam meter. Radius maksimum yang diizinkan adalah 50.000 meter.
type
— Membatasi hasil ke tempat yang cocok dengan jenis yang ditentukan. Hanya satu jenis yang boleh ditetapkan (jika lebih dari satu jenis disediakan, semua jenis setelah entri pertama akan diabaikan). Lihat daftar jenis yang didukung.
Anda juga harus meneruskan metode callback ke textSearch()
untuk menangani objek hasil dan respons google.maps.places.PlacesServiceStatus
.
var map; var service; var infowindow; function initialize() { var pyrmont = new google.maps.LatLng(-33.8665433,151.1956316); map = new google.maps.Map(document.getElementById('map'), { center: pyrmont, zoom: 15 }); var request = { location: pyrmont, radius: '500', query: 'restaurant' }; service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { for (var i = 0; i < results.length; i++) { var place = results[i]; createMarker(results[i]); } } }
Respons Penelusuran
Kode Status
Objek respons PlacesServiceStatus
berisi status permintaan, dan mungkin berisi informasi proses debug untuk membantu Anda melacak penyebab kegagalan permintaan tempat. Nilai status yang mungkin adalah:
INVALID_REQUEST
: Permintaan ini tidak valid.OK
: Respons berisi hasil yang valid.OVER_QUERY_LIMIT
: Halaman web telah melampaui kuota permintaannya.REQUEST_DENIED
: Halaman web tidak diizinkan menggunakan PlacesService.UNKNOWN_ERROR
: Permintaan PlacesService tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.ZERO_RESULTS
: Tidak ada hasil yang ditemukan untuk permintaan ini.
Hasil Place Search
Fungsi findPlace()
, nearbySearch()
, dan
textSearch()
menampilkan array objek
PlaceResult
.
Setiap objek PlaceResult
dapat menyertakan properti berikut:
business_status
menunjukkan status operasional tempat, jika berupa bisnis. Properti ini dapat berisi salah satu dari nilai berikut:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
tidak akan ditampilkan.formatted_address
adalah string yang berisi alamat tempat ini yang dapat dibaca orang. Propertiformatted_address
hanya ditampilkan untuk Text Search.Sering kali alamat ini sama dengan alamat pos. Harap ingat bahwa beberapa negara, seperti Inggris Raya, tidak mengizinkan distribusi alamat pos sebenarnya karena adanya pembatasan pemberian lisensi.
Alamat yang diformat secara logis terdiri dari satu atau beberapa komponen alamat. Misalnya, alamat "111 8th Avenue, New York, NY" terdiri atas komponen berikut: "111" (nomor jalan), "8th Avenue" (rute), "New York" (kota), dan "NY" (negara bagian AS).
Jangan mengurai alamat berformat secara terprogram. Sebagai gantinya, Anda harus menggunakan komponen alamat individual, yang disertakan oleh respons API selain kolom alamat yang diformat.
geometry
: Informasi yang terkait dengan geometri suatu tempat. Hal ini mencakup:location
memberikan garis lintang dan bujur suatu tempat.viewport
menentukan area pandang yang diinginkan pada peta saat menampilkan tempat ini.
permanently_closed
(tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut tutup permanen atau sementara waktu (nilaitrue
). Jangan gunakanpermanently_closed
. Sebagai gantinya, gunakanbusiness_status
untuk mendapatkan status operasional bisnis.plus_code
(lihat Open Location Code dan Plus Codes) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8000 derajat x 1/8000 derajat (sekitar 14 m x 14 m di khatulistiwa) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat tanpa alamat jelas (jika bangunan tidak diberi nomor atau jalan tidak diberi nama).Plus Codes diformat sebagai kode global dan kode gabungan:
global_code
adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih (849VCWC8+R9).compound_code
adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit (CWC8+R9, Mountain View, CA, USA). Jangan mengurai konten ini secara terprogram.
html_attributions
: Array atribusi yang harus Anda tampilkan saat menampilkan hasil penelusuran. Setiap entri dalam array berisi teks HTML untuk atribusi tunggal. Catatan: Array ini adalah kumpulan semua atribusi untuk seluruh respons penelusuran. Oleh karena itu, semua objekPlaceResult
dalam respons berisi daftar atribusi yang identik.icon
menampilkan URL untuk ikon PNG berwarna dengan ukuran 71x71 piksel.icon_mask_base_uri
menampilkan URL dasar untuk ikon tidak berwarna, tanpa ekstensi .svg atau .png.icon_background_color
menampilkan kode warna heksadesimal default untuk kategori tempat.name
: Nama tempat.opening_hours
dapat berisi informasi berikut:open_now
adalah nilai boolean yang menunjukkan apakah tempat tersebut buka pada saat ini (Tidak digunakan lagi di Library Places, Maps JavaScript API, gunakanutc_offset_minutes
sebagai gantinya).
place_id
adalah ID tekstual yang secara unik mengidentifikasi tempat. Untuk mengambil informasi tentang tempat, teruskan ID ini dalam permintaan Place Details. Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.rating
berisi rating tempat, dari 0,0 hingga 5,0, berdasarkan gabungan ulasan pengguna.types
Array jenis untuk tempat ini (misalnya,["political", "locality"]
atau["restaurant", "lodging"]
). Array ini dapat berisi beberapa nilai, atau mungkin kosong. Nilai baru dapat dimasukkan tanpa pemberitahuan sebelumnya. Lihat daftar jenis yang didukung.vicinity
: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor gedung, dan lokalitas, tetapi bukan provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilaivicinity
berupa5/48 Pirrama Road, Pyrmont
.
Mengakses Hasil Tambahan
Secara default, setiap penelusuran tempat menampilkan hingga 20 hasil per kueri. Namun, setiap penelusuran dapat menampilkan hingga 60 hasil, yang terbagi dalam tiga halaman.
Halaman tambahan tersedia melalui objek PlaceSearchPagination
. Untuk mengakses halaman tambahan, Anda harus mengambil objek
PlaceSearchPagination
melalui fungsi callback. Objek
PlaceSearchPagination
didefinisikan sebagai:
hasNextPage
properti boolean yang menunjukkan apakah tersedia hasil lebih lanjut.true
saat ada halaman hasil tambahan.nextPage()
fungsi yang akan menampilkan kumpulan hasil berikutnya. Setelah menjalankan penelusuran, Anda harus menunggu dua detik sebelum halaman hasil berikutnya akan tersedia.
Untuk melihat kumpulan hasil berikutnya, panggil nextPage
.
Setiap halaman hasil harus ditampilkan sebelum menampilkan halaman hasil
berikutnya. Perhatikan, setiap penelusuran dihitung sebagai satu permintaan terhadap
batas penggunaan Anda.
Contoh di bawah menunjukkan cara mengubah fungsi callback untuk
mengambil objek PlaceSearchPagination
, sehingga Anda dapat mengeluarkan
beberapa permintaan penelusuran.
TypeScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap(): void { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map( document.getElementById("map") as HTMLElement, { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", } as google.maps.MapOptions ); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage: () => void | false; const moreButton = document.getElementById("more") as HTMLButtonElement; moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, ( results: google.maps.places.PlaceResult[] | null, status: google.maps.places.PlacesServiceStatus, pagination: google.maps.places.PlaceSearchPagination | null ) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } } ); } function addPlaces( places: google.maps.places.PlaceResult[], map: google.maps.Map ) { const placesList = document.getElementById("places") as HTMLElement; for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon!, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name!, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name!; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry!.location!); }); } } } declare global { interface Window { initMap: () => void; } } window.initMap = initMap;
JavaScript
// This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> function initMap() { // Create the map. const pyrmont = { lat: -33.866, lng: 151.196 }; const map = new google.maps.Map(document.getElementById("map"), { center: pyrmont, zoom: 17, mapId: "8d193001f940fde3", }); // Create the places service. const service = new google.maps.places.PlacesService(map); let getNextPage; const moreButton = document.getElementById("more"); moreButton.onclick = function () { moreButton.disabled = true; if (getNextPage) { getNextPage(); } }; // Perform a nearby search. service.nearbySearch( { location: pyrmont, radius: 500, type: "store" }, (results, status, pagination) => { if (status !== "OK" || !results) return; addPlaces(results, map); moreButton.disabled = !pagination || !pagination.hasNextPage; if (pagination && pagination.hasNextPage) { getNextPage = () => { // Note: nextPage will call the same handler function as the initial call pagination.nextPage(); }; } }, ); } function addPlaces(places, map) { const placesList = document.getElementById("places"); for (const place of places) { if (place.geometry && place.geometry.location) { const image = { url: place.icon, size: new google.maps.Size(71, 71), origin: new google.maps.Point(0, 0), anchor: new google.maps.Point(17, 34), scaledSize: new google.maps.Size(25, 25), }; new google.maps.Marker({ map, icon: image, title: place.name, position: place.geometry.location, }); const li = document.createElement("li"); li.textContent = place.name; placesList.appendChild(li); li.addEventListener("click", () => { map.setCenter(place.geometry.location); }); } } } window.initMap = initMap;
Mencoba Contoh
Place Details
Selain menyediakan daftar tempat dalam suatu area, layanan Places juga menampilkan informasi detail tentang tempat tertentu. Setelah tempat ditampilkan dalam respons penelusuran tempat, ID tempat dapat digunakan untuk meminta detail tambahan tentang tempat tersebut, seperti alamat lengkap, nomor telepon, rating pengguna, ulasan pengguna, dll.
Permintaan Place Details
Place Details diminta dengan panggilan ke metode
getDetails()
layanan.
service = new google.maps.places.PlacesService(map); service.getDetails(request, callback);
Metode ini menggunakan permintaan, yang berisi placeId
untuk tempat yang diinginkan, dan kolom yang menunjukkan jenis data Places yang akan ditampilkan. Pelajari lebih lanjut
cara mereferensikan tempat dengan ID tempat.
Cara ini juga membutuhkan metode callback, yang perlu menangani kode status yang diteruskan
dalam respons google.maps.places.PlacesServiceStatus
, serta
objek google.maps.places.PlaceResult
.
var request = { placeId: 'ChIJN1t_tDeuEmsRUsoyG83frY4', fields: ['name', 'rating', 'formatted_phone_number', 'geometry'] }; service = new google.maps.places.PlacesService(map); service.getDetails(request, callback); function callback(place, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { createMarker(place); } }
Kolom (Place Details)
Parameterfields
menggunakan array string (nama kolom).
Gunakan parameter fields
untuk menentukan array jenis data tempat yang akan ditampilkan.
Contoh: fields: ['address_components', 'opening_hours', 'geometry']
.
Gunakan titik saat menentukan nilai gabungan. Contoh: opening_hours.weekday_text
.
Kolom sesuai dengan hasil Place Details, dan dibagi menjadi tiga kategori penagihan: Basic, Contact, dan Atmosphere. Kolom Basic ditagih dengan tarif dasar dan tidak dikenai biaya tambahan. Kolom Contact dan Atmosphere ditagih dengan tarif lebih tinggi. Lihat sheet harga
untuk mengetahui informasi selengkapnya. Atribusi (html_attributions
) selalu ditampilkan dengan setiap panggilan, terlepas dari apakah kolom telah diminta atau tidak.
Basic
Kategori Basic mencakup kolom berikut:
address_components
, adr_address
, business_status
,
formatted_address
, geometry
, icon
,
icon_mask_base_uri
, icon_background_color
,name
,
permanently_closed
(tidak digunakan lagi), photo
, place_id
, plus_code
, type
, url
, utc_offset
(tidak digunakan lagi di Library Places, Maps JavaScript API), utc_offset_minutes
, vicinity
Contact
Kategori Contact mencakup kolom berikut:
formatted_phone_number
, international_phone_number
,
opening_hours
, website
Atmosphere
Kategori Atmosphere mencakup kolom berikut:
price_level
, rating
, reviews
,
user_ratings_total
Pelajari kolom tempat lebih lanjut. Untuk informasi selengkapnya tentang cara penagihan permintaan data Tempat, lihat Penggunaan dan Penagihan.
Respons Place Details
Kode Status
Objek respons PlacesServiceStatus
berisi status
permintaan, dan mungkin berisi informasi proses debug untuk membantu Anda melacak
penyebab kegagalan permintaan Place Details. Nilai status yang mungkin adalah:
INVALID_REQUEST
: Permintaan ini tidak valid.OK
: Respons berisi hasil yang valid.OVER_QUERY_LIMIT
: Halaman web telah melampaui kuota permintaannya.NOT_FOUND
: Lokasi yang dirujuk tidak ditemukan dalam database Tempat.REQUEST_DENIED
: Halaman web tidak diizinkan menggunakan PlacesService.UNKNOWN_ERROR
: Permintaan PlacesService tidak dapat diproses karena error server. Permintaan mungkin berhasil jika Anda mencoba lagi.ZERO_RESULTS
: Tidak ada hasil yang ditemukan untuk permintaan ini.
Hasil Place Details
Panggilan getDetails()
yang berhasil akan menampilkan objek
PlaceResult
dengan properti berikut:
address_components
: Array yang berisi komponen terpisah yang berlaku untuk alamat ini.Setiap komponen alamat biasanya berisi kolom berikut:
types[]
adalah array yang menunjukkan jenis komponen alamat. Lihat daftar jenis yang didukung.long_name
adalah deskripsi teks lengkap atau nama komponen alamat seperti yang ditampilkan oleh Geocoder.short_name
adalah nama tekstual yang disingkat untuk komponen alamat, jika tersedia. Misalnya, komponen alamat untuk negara bagian Alaska dapat memilikilong_name
"Alaska" danshort_name
"AK" menggunakan 2 huruf singkatan istilah pos.
Perhatikan fakta berikut tentang array
address_components[]
:- Array komponen alamat dapat berisi lebih banyak komponen daripada
formatted_address
. - Array tidak harus selalu menyertakan semua entitas politik yang
berisi alamat, selain dari yang disertakan dalam
formatted_address
. Untuk mengambil semua entitas politik yang berisi alamat tertentu, Anda harus menggunakan geocoding terbalik, yang meneruskan garis lintang/bujur alamat sebagai parameter ke permintaan tersebut. - Format respons tidak dijamin tetap sama di antara
permintaan. Secara khusus, jumlah
address_components
bervariasi berdasarkan alamat yang diminta dan dapat berubah dari waktu ke waktu untuk alamat yang sama. Komponen dapat mengubah posisi dalam array. Jenis komponen dapat berubah. Komponen tertentu mungkin tidak ada dalam respons berikutnya.
business_status
menunjukkan status operasional tempat, jika berupa bisnis. Properti ini dapat berisi salah satu dari nilai berikut:OPERATIONAL
CLOSED_TEMPORARILY
CLOSED_PERMANENTLY
business_status
tidak akan ditampilkan.formatted_address
: Alamat tempat ini yang dapat dibaca orang.Sering kali alamat ini sama dengan alamat pos. Harap ingat bahwa beberapa negara, seperti Inggris Raya, tidak mengizinkan distribusi alamat pos sebenarnya karena adanya pembatasan pemberian lisensi.
Alamat yang diformat secara logis terdiri dari satu atau beberapa komponen alamat. Misalnya, alamat "111 8th Avenue, New York, NY" terdiri atas komponen berikut: "111" (nomor jalan), "8th Avenue" (rute), "New York" (kota), dan "NY" (negara bagian AS).
Jangan mengurai alamat berformat secara terprogram. Sebagai gantinya, Anda harus menggunakan komponen alamat individual, yang disertakan oleh respons API selain kolom alamat yang diformat.
formatted_phone_number
: Nomor telepon tempat, yang diformat sesuai dengan konvensi penomoran di wilayah tersebut.geometry
: Informasi yang terkait dengan geometri suatu tempat. Hal ini mencakup:location
memberikan garis lintang dan bujur suatu tempat.viewport
menentukan area pandang yang diinginkan pada peta saat menampilkan tempat ini.
permanently_closed
(tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut tutup permanen atau sementara waktu (nilaitrue
). Jangan gunakanpermanently_closed
. Sebagai gantinya, gunakanbusiness_status
untuk mendapatkan status operasional bisnis.plus_code
(lihat Open Location Code dan Plus Codes) adalah referensi lokasi yang dienkode, yang berasal dari koordinat lintang dan bujur, yang mewakili area: 1/8000 derajat x 1/8000 derajat (sekitar 14 m x 14 m di khatulistiwa) atau lebih kecil. Plus Codes dapat digunakan sebagai pengganti alamat di tempat tanpa alamat jelas (jika bangunan tidak diberi nomor atau jalan tidak diberi nama).Plus Codes diformat sebagai kode global dan kode gabungan:
global_code
adalah kode area berisi 4 karakter dan kode lokal berisi 6 karakter atau lebih (849VCWC8+R9).compound_code
adalah kode lokal berisi 6 karakter atau lebih dengan lokasi yang eksplisit (CWC8+R9, Mountain View, CA, USA). Jangan mengurai konten ini secara terprogram.
html_attributions
: Teks atribusi yang akan ditampilkan untuk hasil tempat ini.icon
: URL ke resource gambar yang bisa digunakan untuk menampilkan jenis tempat ini.international_phone_number
berisi nomor telepon tempat tersebut dalam format internasional. Format internasional menyertakan kode negara dan diawali dengan tanda tambah (+). Misalnya,international_phone_number
untuk kantor Google di Sydney, Australia adalah+61 2 9374 4000
.name
: Nama tempat.utc_offset
Tidak digunakan lagi di Places Library, Maps JavaScript API, gunakanutc_offset_minutes
sebagai gantinya.utc_offset_minutes
berisi offset jumlah menit antara zona waktu tempat ini sekarang dari UTC. Misalnya, untuk tempat di Sydney, Australia saat terjadi penyesuaian waktu musim panas akan menjadi 660 (+11 jam dari UTC), dan untuk tempat di California di luar penyesuaian waktu musim panas akan menjadi -480 (-8 jam dari UTC).opening_hours
berisi informasi berikut:open_now
(Tidak digunakan lagi di Places Library, Maps JavaScript API; gunakan opening_hours.isOpen() sebagai gantinya. Tonton video ini untuk mengetahui cara menggunakanisOpen
dengan Place Details.) adalah nilai boolean yang menunjukkan apakah tempat tersebut buka pada waktu saat ini.periods[]
adalah array jangka waktu buka yang mencakup tujuh hari, mulai dari hari Minggu, dalam urutan kronologis. Setiap jangka waktu berisi:open
berisi sepasang objek hari dan waktu yang menjelaskan kapan tempat tersebut buka:day
angka 0–6, yang menyatakan hari-hari dalam seminggu, mulai hari Minggu. Misalnya, 2 berarti Selasa.time
dapat berisi waktu dalam sehari dalam format 24 jam jjmm (nilainya berkisar 0000–2359).time
akan dilaporkan dalam zona waktu tempat tersebut.
close
dapat berisi pasangan objek hari dan waktu yang menjelaskan kapan tempat tersebut tutup. Catatan: Jika tempat selalu buka, bagianclose
akan hilang dari respons. Aplikasi dapat selalu berpatokan pada kondisi selalu-buka yang direpresentasikan sebagai jangka waktuopen
yang berisiday
dengan nilai 0 dantime
dengan nilai 0000, dan tanpaclose
.
weekday_text
adalah array berisi tujuh string yang menyatakan jam buka yang telah diformat untuk setiap hari dalam seminggu. Jika parameterlanguage
telah ditentukan dalam permintaan Place Details, Places Service akan memformat dan melokalkan jam buka secara tepat untuk bahasa tersebut. Urutan elemen dalam array ini bergantung pada parameterlanguage
. Beberapa bahasa memulai pekan pada hari Senin, sementara yang lain mulai pada hari Minggu.
permanently_closed
(tidak digunakan lagi) adalah flag boolean yang menunjukkan apakah tempat tersebut tutup permanen atau sementara waktu (nilaitrue
). Jangan gunakanpermanently_closed
. Sebagai gantinya, gunakanbusiness_status
untuk mendapatkan status operasional bisnis.photos[]
: array objekPlacePhoto
.PlacePhoto
dapat digunakan untuk mendapatkan foto dengan metodegetUrl()
, atau Anda dapat memeriksa objek untuk mengetahui nilai berikut:height
: tinggi maksimum gambar, dalam piksel.width
: lebar maksimum gambar, dalam piksel.html_attributions
: teks Atribusi yang akan ditampilkan bersama foto tempat ini.
place_id
: ID tekstual yang secara unik mengidentifikasi tempat dan dapat digunakan untuk mengambil informasi tentang tempat melalui permintaan Place Details. Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.rating
: Peringkat tempat ini, dari 0,0 hingga 5,0, berdasarkan gabungan ulasan pengguna.reviews
array yang dapat berisi hingga lima ulasan. Setiap ulasan terdiri dari beberapa komponen:aspects[]
berisi array objekPlaceAspectRating
, yang masing-masing memberikan rating satu atribut untuk tempat usaha tersebut. Objek pertama dalam array dianggap sebagai aspek utama. SetiapPlaceAspectRating
ditentukan sebagai:type
nama aspek yang sedang diberi peringkat. Jenis-jenis berikut didukung:appeal
,atmosphere
,decor
,facilities
,food
,overall
,quality
, danservice
.rating
rating dari pengguna untuk aspek tertentu dari 0 hingga 3.
author_name
nama pengguna yang mengirim ulasan. Ulasan anonim diatribusikan ke "Pengguna Google". Jika parameter bahasa ditetapkan, frasa "Pengguna Google" akan menampilkan string yang dilokalkan.author_url
URL ke profil Google+ pengguna, jika tersedia.language
kode bahasa IETF yang menunjukkan bahasa yang digunakan dalam ulasan pengguna. Kolom ini berisi tag bahasa utama saja, dan bukan tag sekunder yang menunjukkan negara atau wilayah. Misalnya, semua ulasan dalam bahasa Inggris akan diberi tag 'en', dan bukan 'en-AU' atau 'en-UK' dan seterusnya.rating
rating pengguna secara keseluruhan untuk tempat ini. Rating ini menggunakan bilangan bulat, berkisar dari 1 hingga 5.text
ulasan pengguna. Saat mengulas sebuah lokasi dengan Google Places, ulasan teks dianggap opsional; karena itu, kolom ini mungkin kosong.
types
Array jenis untuk tempat ini (misalnya,["political", "locality"]
atau["restaurant", "lodging"]
). Array ini dapat berisi beberapa nilai, atau mungkin kosong. Nilai baru dapat dimasukkan tanpa pemberitahuan sebelumnya. Lihat daftar jenis yang didukung.url
: URL halaman resmi Google untuk tempat ini. Halaman ini adalah halaman milik Google berisi informasi terbaik yang tersedia tentang tempat ini. Aplikasi harus menautkan ke atau menyematkan halaman ini pada setiap layar yang menampilkan hasil detail tentang tempat tersebut kepada pengguna.vicinity
: Alamat yang disederhanakan untuk tempat, termasuk nama jalan, nomor gedung, dan lokalitas, tetapi bukan provinsi/negara bagian, kode pos, atau negara. Misalnya, kantor Google di Sydney, Australia memiliki nilaivicinity
berupa5/48 Pirrama Road, Pyrmont
. Propertivicinity
hanya ditampilkan untuk Nearby Search.website
mencantumkan situs resmi untuk tempat ini, seperti halaman beranda bisnis.
Catatan: Rating multidimensi mungkin tidak tersedia untuk semua lokasi. Jika ulasan terlalu sedikit, respons detail akan menyertakan rating lama dengan skala 0,0 hingga 5,0 (jika tersedia) atau tidak ada rating sama sekali.
Menggunakan komponen Place Overview
Catatan: Contoh ini menggunakan library open source. Lihat README untuk mendapatkan dukungan dan dukungan terkait dengan library.
Coba komponen web. Gunakan Komponen web Ringkasan Tempat untuk mendapatkan detail tempat dengan representasi visual.
![Gambar yang menampilkan variasi ukuran x-kecil, kecil, medium, besar, dan x-besar dari
Komponen Place Overview ditampilkan berdasarkan kolom ukuran yang dimasukkan oleh pengguna.](https://developers-dot-devsite-v2-prod.appspot.com/static/maps/documentation/javascript/images/place-overview-sizes.png?authuser=19&hl=id)
Merujuk sebuah Tempat dengan ID Tempat
ID tempat adalah referensi unik untuk tempat di Google Maps. ID Tempat tersedia untuk sebagian besar lokasi, termasuk lokasi bisnis, tempat terkenal, taman, dan persimpangan.
Untuk menggunakan ID tempat dalam aplikasi, Anda harus terlebih dahulu menemukan ID, yang tersedia di PlaceResult
dari permintaan Place Search atau Place Details.
Anda kemudian dapat menggunakan ID tempat ini untuk menemukan
Place
Details.
ID tempat dikecualikan dari pembatasan penyimpanan cache yang disebutkan di Pasal 3.2.3(b) dalam Persyaratan Layanan Google Maps Platform. Oleh karena itu, Anda dapat menyimpan nilai ID tempat untuk digunakan nanti. Untuk praktik terbaik saat menyimpan ID tempat, lihat ringkasan ID tempat.
var map; function initialize() { // Create a map centered in Pyrmont, Sydney (Australia). map = new google.maps.Map(document.getElementById('map'), { center: {lat: -33.8666, lng: 151.1958}, zoom: 15 }); // Search for Google's office in Australia. var request = { location: map.getCenter(), radius: '500', query: 'Google Sydney' }; var service = new google.maps.places.PlacesService(map); service.textSearch(request, callback); } // Checks that the PlacesServiceStatus is OK, and adds a marker // using the place ID and location from the PlacesService. function callback(results, status) { if (status == google.maps.places.PlacesServiceStatus.OK) { var marker = new google.maps.Marker({ map: map, place: { placeId: results[0].place_id, location: results[0].geometry.location } }); } } google.maps.event.addDomListener(window, 'load', initialize);
Place Photos
Fitur Place Photo memungkinkan Anda menambahkan materi fotografi berkualitas tinggi ke situs Anda. Layanan Photo memberi Anda akses ke jutaan foto yang tersimpan dalam database Places dan Google+ Local. Jika Anda mengambil informasi tempat menggunakan permintaan Place Details, referensi foto akan ditampilkan untuk materi fotografi yang relevan. Permintaan Nearby Search dan Text Search juga akan menampilkan satu referensi foto per tempat, jika relevan. Dengan layanan Photo, Anda kemudian bisa mengakses foto yang direferensikan dan mengubah ukuran gambar ke ukuran yang optimal untuk aplikasi Anda.
Array objek PlacePhoto
akan ditampilkan sebagai bagian dari
objek PlaceResult
untuk permintaan getDetails()
,
textSearch()
, atau
nearbySearch()
yang dibuat terhadap PlacesService
.
Catatan: Jumlah foto yang ditampilkan akan bervariasi menurut permintaan.
- Nearby Search atau Text Search akan menampilkan maksimal satu
objek
PlacePhoto
. - Permintaan Details akan menampilkan hingga sepuluh objek
PlacePhoto
.
Anda dapat meminta URL untuk gambar terkait dengan memanggil
metode PlacePhoto.getUrl()
, serta meneruskan objek
PhotoOptions
yang valid. Objek PhotoOptions
memungkinkan Anda menentukan tinggi dan lebar maksimum yang diinginkan dari gambar. Jika Anda menentukan nilai untuk maxHeight
dan maxWidth
, layanan Photo akan mengubah ukuran gambar menurut ukuran yang lebih kecil, dengan tetap mempertahankan rasio aspek asli.
Cuplikan kode berikut menerima objek tempat, dan menambahkan penanda ke peta jika ada fotonya. Gambar penanda default digantikan dengan versi kecil dari foto tersebut.
function createPhotoMarker(place) { var photos = place.photos; if (!photos) { return; } var marker = new google.maps.Marker({ map: map, position: place.geometry.location, title: place.name, icon: photos[0].getUrl({maxWidth: 35, maxHeight: 35}) }); }
Foto yang dkembalikan oleh layanan Photo berasal dari berbagai lokasi, termasuk foto dari pemilik bisnis dan pengguna. Umumnya,
foto ini dapat digunakan tanpa atribusi, atau atribusi yang diperlukan
akan disertakan sebagai bagian dari gambar. Namun, jika elemen
photo
yang ditampilkan menyertakan nilai di
kolom html_attributions
, Anda harus menyertakan atribusi tambahan dalam aplikasi di mana pun Anda menampilkan gambar.