Pengantar
Autocomplete adalah fitur Places Library di Maps JavaScript API. Anda dapat menggunakan Autocomplete untuk memberi aplikasi Anda perilaku prediksi penelusuran di kolom penelusuran Google Maps. Layanan Autocomplete dapat mencocokkan kata dan substring lengkap, yang me-resolve nama tempat, alamat, dan Plus Codes. Karena itu aplikasi dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat secara real time. Seperti yang ditentukan oleh Places API, 'tempat' dapat berupa tempat usaha, lokasi geografis, atau lokasi menarik terkemuka.
Memulai
Sebelum menggunakan Places Library 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 sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak tercantum, aktifkan API tersebut:
- Di bagian atas halaman, pilih ENABLE API 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.
Ringkasan class
API ini menawarkan dua jenis widget pelengkapan otomatis, yang masing-masing dapat Anda tambahkan melalui class Autocomplete
dan SearchBox
.
Selain itu, Anda dapat menggunakan class AutocompleteService
untuk mengambil hasil pelengkapan otomatis secara terprogram (lihat Referensi Maps JavaScript API: class AutocompleteService).
Berikut rangkuman class yang tersedia:
-
Autocomplete
menambahkan kolom input teks ke halaman web Anda, dan memantau pengisian karakter pada kolom tersebut. Saat pengguna memasukkan teks, pelengkapan otomatis akan menampilkan prediksi tempat dalam bentuk daftar pilihan dropdown. Jika pengguna memilih tempat dari daftar tersebut, informasi tentang tempat akan ditampilkan ke objek pelengkapan otomatis, dan dapat diambil oleh aplikasi Anda. Lihat detailnya di bawah. -
SearchBox
menambahkan kolom input teks ke halaman web Anda, dengan cara yang sama sepertiAutocomplete
. Perbedaannya adalah sebagai berikut:- Perbedaan utama ada pada hasil yang muncul dalam daftar pilihan.
SearchBox
menyediakan daftar prediksi tambahan yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) dan istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza in new', daftar pilihan mungkin menyertakan frasa 'pizza in New York, NY' serta nama-nama berbagai gerai pizza. SearchBox
menawarkan lebih sedikit opsi daripadaAutocomplete
untuk membatasi penelusuran. Pada yang pertama, Anda dapat mengarahkan penelusuran keLatLngBounds
yang diberikan. Pada yang berikutnya, Anda bisa membatasi penelusuran ke negara tertentu dan jenis tempat tertentu, serta menetapkan batasnya. Untuk informasi selengkapnya, lihat di bawah.
- Perbedaan utama ada pada hasil yang muncul dalam daftar pilihan.
- Anda dapat membuat objek
AutocompleteService
untuk mengambil prediksi secara terprogram. PanggilgetPlacePredictions()
untuk mengambil tempat yang cocok, atau panggilgetQueryPredictions()
untuk mengambil tempat yang cocok beserta istilah penelusuran yang disarankan. Catatan:AutocompleteService
tidak menambahkan kontrol UI apa pun. Sebagai gantinya, metode di atas menampilkan array objek prediksi. Setiap objek prediksi berisi teks prediksi, serta informasi referensi dan detail tentang cara menyesuaikan hasilnya dengan masukan pengguna. Lihat detailnya di bawah.
Menambahkan widget Autocomplete
Widget Autocomplete
membuat kolom input teks di halaman web Anda, memberikan prediksi tempat dalam daftar pilihan UI, dan menampilkan detail tempat sebagai respons terhadap permintaan getPlace()
. Setiap entri dalam
daftar pilihan menunjukkan satu tempat (seperti yang ditentukan oleh Places API).
Konstruktor Autocomplete
menggunakan dua argumen:
- Elemen
input
HTML dari jenistext
. Ini adalah kolom input yang akan dipantau oleh layanan pelengkapan otomatis dan untuk melampirkan hasilnya. - Argumen
AutocompleteOptions
opsional, yang dapat berisi properti berikut:- Array data
fields
yang akan disertakan dalam responsPlace Details
untukPlaceResult
yang dipilih pengguna. Jika properti tidak ditetapkan atau jika['ALL']
diteruskan, semua kolom yang tersedia akan ditampilkan dan ditagih (hal ini tidak direkomendasikan untuk deployment produksi). Untuk mengetahui daftar kolom, lihatPlaceResult
. - Array
types
yang menentukan jenis eksplisit atau koleksi jenis, seperti yang tercantum dalam jenis yang didukung. Jika tidak ada jenis yang ditentukan, semua jenis akan ditampilkan. bounds
adalah objekgoogle.maps.LatLngBounds
yang menentukan area untuk menelusuri tempat. Hasilnya dibiaskan terhadap, tetapi tidak terbatas pada, tempat yang berada dalam batas ini.strictBounds
adalahboolean
yang menentukan apakah API hanya boleh menampilkan tempat yang benar-benar berada dalam wilayah yang ditentukan olehbounds
yang diberikan. API tidak menampilkan hasil di luar wilayah ini meskipun cocok dengan input pengguna.componentRestrictions
dapat digunakan untuk membatasi hasil ke grup tertentu. Saat ini, Anda dapat menggunakancomponentRestrictions
untuk memfilter hingga 5 negara. Negara harus diteruskan berupa dua karakter kode negara yang kompatibel dengan ISO 3166-1 Alpha-2. Beberapa negara harus diteruskan sebagai daftar kode negara.Catatan: Jika Anda menerima hasil yang tidak terduga dengan kode negara, pastikan Anda menggunakan kode yang mencakup negara, wilayah dependen, dan area minat geografis khusus yang Anda inginkan. Anda dapat menemukan informasi kode di Wikipedia: List of ISO 3166 country codes (Wikipedia: Daftar kode negara ISO 3166) atau ISO Online Browsing Platform (Platform Penjelajahan Online ISO).
placeIdOnly
dapat digunakan untuk memerintahkan widgetAutocomplete
agar hanya mengambil ID Tempat. Saat memanggilgetPlace()
pada objekAutocomplete
,PlaceResult
yang disediakan hanya akan memiliki propertiplace id
,types
, danname
yang ditetapkan. Anda dapat menggunakan ID tempat yang ditampilkan dengan panggilan ke layanan Places, Geocoding, Directions, atau Distance Matrix.
- Array data
Membatasi prediksi Autocomplete
Secara default, Place Autocomplete menampilkan semua jenis tempat, dengan kecenderungan prediksi di dekat lokasi pengguna, dan mengambil semua kolom data yang tersedia untuk tempat yang dipilih pengguna. Tetapkan opsi Place Autocomplete untuk memberikan prediksi yang lebih relevan berdasarkan kasus penggunaan Anda.
Menetapkan opsi saat pembuatan
Konstruktor Autocomplete
menerima parameter AutocompleteOptions
untuk menetapkan batasan saat pembuatan widget. Contoh berikut menetapkan opsi bounds
, componentRestrictions
, dan types
untuk meminta tempat jenis establishment
, yang memprioritaskan tempat dalam area geografis yang ditentukan dan membatasi prediksi hanya ke tempat di Amerika Serikat. Menetapkan opsi
fields
akan menentukan informasi yang akan ditampilkan tentang tempat yang dipilih pengguna.
Panggil setOptions()
untuk mengubah nilai opsi untuk widget yang ada.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input") as HTMLInputElement; const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
JavaScript
const center = { lat: 50.064192, lng: -130.605469 }; // Create a bounding box with sides ~10km away from the center point const defaultBounds = { north: center.lat + 0.1, south: center.lat - 0.1, east: center.lng + 0.1, west: center.lng - 0.1, }; const input = document.getElementById("pac-input"); const options = { bounds: defaultBounds, componentRestrictions: { country: "us" }, fields: ["address_components", "geometry", "icon", "name"], strictBounds: false, }; const autocomplete = new google.maps.places.Autocomplete(input, options);
Menentukan kolom data
Tentukan kolom data agar tidak ditagih untuk SKU Data Places yang tidak Anda perlukan. Sertakan properti fields
dalam
AutocompleteOptions
yang diteruskan ke konstruktor widget, seperti yang ditunjukkan dalam contoh sebelumnya, atau panggil setFields()
pada objek Autocomplete
yang ada.
autocomplete.setFields(["place_id", "geometry", "name"]);
Menentukan bias dan batas area penelusuran untuk Autocomplete
Anda dapat membiaskan hasil pelengkapan otomatis untuk mendukung suatu perkiraan lokasi atau area, dengan cara berikut:
- Menetapkan batas saat pembuatan objek
Autocomplete
. - Mengubah batas
Autocomplete
yang sudah ada. - Menetapkan batas ke area pandang peta.
- Membatasi penelusuran pada batas.
- Membatasi penelusuran pada negara tertentu.
Contoh sebelumnya menunjukkan penetapan batas saat pembuatan. Contoh berikut menunjukkan teknik bias lainnya.
Mengubah batas pada Autocomplete yang ada
Panggil setBounds()
untuk mengubah area penelusuran pada
Autocomplete
yang ada menjadi batas persegi panjang.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Menetapkan batas ke area pandang peta
Gunakan bindTo()
untuk membiaskan hasilnya ke area pandang peta, meskipun area pandang tersebut berubah.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Gunakan unbind()
untuk menghapus prediksi Autocomplete dari area pandang peta.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Membatasi penelusuran ke batas saat ini
Tetapkan opsi strictBounds
untuk membatasi hasil ke batas saat ini, baik berdasarkan area pandang peta maupun batas persegi panjang.
autocomplete.setOptions({ strictBounds: true });
Membatasi prediksi ke negara tertentu
Gunakan opsi componentRestrictions
atau panggil setComponentRestrictions()
untuk membatasi penelusuran pelengkapan otomatis ke kumpulan spesifik yang berisi hingga lima negara.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Membatasi jenis tempat
Gunakan opsi types
atau panggil setTypes()
untuk membatasi prediksi ke jenis tempat tertentu. Batasan ini menentukan jenis atau kumpulan jenis,
seperti yang tercantum dalam Jenis Tempat.
Jika tidak ada batasan yang ditentukan, semua jenis akan ditampilkan.
Untuk nilai opsi types
atau nilai yang diteruskan ke setTypes()
, Anda dapat menentukan:
Array yang berisi hingga lima nilai dari Tabel 1 atauTabel 2 dari Jenis Tempat. Contoh:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Atau:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Satu filter di Tabel 3 dari Jenis Tempat. Anda hanya dapat menentukan satu nilai dari Tabel 3.
Permintaan akan ditolak jika:
- Anda menentukan lebih dari lima jenis.
- Anda menentukan jenis yang tidak dikenal.
- Anda mencampur semua jenis dari Tabel 1 atau Tabel 2 dengan filter apa pun dari Tabel 3.
Demo Places Autocomplete menunjukkan perbedaan prediksi di antara berbagai jenis tempat.
Mendapatkan informasi tempat
Saat pengguna memilih tempat dari prediksi yang disertakan ke
kolom teks pelengkapan otomatis, layanan akan mengaktifkan peristiwa place_changed
. Untuk mendapatkan detail
tempat:
- Buat pengendali peristiwa untuk peristiwa
place_changed
, dan panggiladdListener()
pada objekAutocomplete
untuk menambahkan pengendali. - Panggil
Autocomplete.getPlace()
pada objekAutocomplete
, untuk mengambil objekPlaceResult
, yang kemudian dapat Anda gunakan untuk mendapatkan lebih banyak informasi tentang tempat yang dipilih.
Secara default, saat pengguna memilih suatu tempat, pelengkapan otomatis menampilkan semua kolom data yang tersedia untuk tempat yang dipilih, dan Anda akan ditagih sebagaimana mestinya.
Gunakan Autocomplete.setFields()
untuk menentukan kolom data tempat yang akan dikembalikan. Baca selengkapnya tentang objek PlaceResult
, termasuk daftar kolom data tempat yang dapat Anda minta. Agar tidak membayar data yang tidak Anda perlukan, pastikan menggunakan Autocomplete.setFields()
untuk menentukan data tempat yang akan digunakan saja.
Properti name
berisi description
dari prediksi Places Autocomplete. Anda dapat membaca selengkapnya tentang description
di dokumentasi Places Autocomplete.
Formulir alamat perlu mendapatkan alamat dalam format terstruktur. Untuk
mengembalikan alamat terstruktur untuk tempat yang dipilih, panggil
Autocomplete.setFields()
dan tentukan kolom address_components
.
Contoh berikut menggunakan pelengkapan otomatis untuk mengisi kolom dalam formulir alamat.
TypeScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": (document.querySelector("#locality") as HTMLInputElement).value = component.long_name; break; case "administrative_area_level_1": { (document.querySelector("#state") as HTMLInputElement).value = component.short_name; break; } case "country": (document.querySelector("#country") as HTMLInputElement).value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); }
JavaScript
function fillInAddress() { // Get the place details from the autocomplete object. const place = autocomplete.getPlace(); let address1 = ""; let postcode = ""; // Get each component of the address from the place details, // and then fill-in the corresponding field on the form. // place.address_components are google.maps.GeocoderAddressComponent objects // which are documented at http://goo.gle/3l5i5Mr for (const component of place.address_components) { // @ts-ignore remove once typings fixed const componentType = component.types[0]; switch (componentType) { case "street_number": { address1 = `${component.long_name} ${address1}`; break; } case "route": { address1 += component.short_name; break; } case "postal_code": { postcode = `${component.long_name}${postcode}`; break; } case "postal_code_suffix": { postcode = `${postcode}-${component.long_name}`; break; } case "locality": document.querySelector("#locality").value = component.long_name; break; case "administrative_area_level_1": { document.querySelector("#state").value = component.short_name; break; } case "country": document.querySelector("#country").value = component.long_name; break; } } address1Field.value = address1; postalField.value = postcode; // After filling the form with address components from the Autocomplete // prediction, set cursor focus on the second address line to encourage // entry of subpremise information such as apartment, unit, or floor number. address2Field.focus(); } window.initAutocomplete = initAutocomplete;
Menyesuaikan teks placeholder
Secara default, kolom teks yang dibuat oleh layanan pelengkapan otomatis berisi teks placeholder standar. Untuk mengubah teks, tetapkan
atribut placeholder
pada elemen input
:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Catatan: Teks placeholder default dilokalkan secara otomatis. Jika Anda menetapkan nilai placeholder sendiri, Anda harus menangani pelokalan nilai tersebut dalam aplikasi Anda. Untuk informasi tentang cara Google Maps JavaScript API memilih bahasa yang akan digunakan, baca dokumentasi tentang pelokalan.
Lihat Menata gaya widget Autocomplete dan SearchBox untuk menyesuaikan tampilan widget.
Menambahkan widget SearchBox
Dengan
SearchBox
, pengguna dapat melakukan penelusuran geografis
berbasis teks, seperti 'pizza in New York' atau 'shoe stores near robson street'.
Anda dapat melampirkan SearchBox
ke kolom teks, dan saat teks dimasukkan, layanan ini akan menampilkan prediksi dalam bentuk menu pilihan drop-down.
SearchBox
menyediakan daftar prediksi tambahan, yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) dan istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza in new', daftar pilihan mungkin menyertakan frasa 'pizza in New York, NY' serta nama-nama berbagai gerai pizza. Jika pengguna memilih tempat dari daftar tersebut,
informasi tentang tempat akan ditampilkan ke objek SearchBox, dan dapat
diambil oleh aplikasi Anda.
Konstruktor SearchBox
menggunakan dua argumen:
- Elemen
input
HTML dari jenistext
. Ini adalah kolom input yang akan dipantau oleh layananSearchBox
dan untuk melampirkan hasilnya. - Argumen
options
, yang dapat berisi propertibounds
:bounds
adalah objekgoogle.maps.LatLngBounds
yang menentukan area untuk menelusuri tempat. Hasilnya dicondongkan ke, tetapi tidak terbatas pada, tempat yang berada dalam batas ini.
Kode berikut menggunakan parameter bounds untuk mencondongkan hasil ke tempat yang ada dalam area geografis tertentu, yang ditetapkan melalui koordinat garis lintang/garis bujur.
var defaultBounds = new google.maps.LatLngBounds( new google.maps.LatLng(-33.8902, 151.1759), new google.maps.LatLng(-33.8474, 151.2631)); var input = document.getElementById('searchTextField'); var searchBox = new google.maps.places.SearchBox(input, { bounds: defaultBounds });
Mengubah area penelusuran untuk SearchBox
Untuk mengubah area penelusuran untuk SearchBox
yang ada, panggil setBounds()
pada objek SearchBox
dan teruskan objek LatLngBounds
yang relevan.
Mendapatkan informasi tempat
Saat pengguna memilih item dari prediksi yang dilampirkan ke kotak penelusuran, layanan akan mengaktifkan peristiwa places_changed
. Anda dapat memanggil getPlaces()
pada objek SearchBox
, untuk mengambil array yang berisi beberapa prediksi, yang masing-masing merupakan objek PlaceResult
.
Untuk informasi selengkapnya tentang objek PlaceResult
, lihat
dokumentasi tentang
hasil detail tempat.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { url: place.icon as string, 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), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }) ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
JavaScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { const places = searchBox.getPlaces(); if (places.length == 0) { return; } // Clear out the old markers. markers.forEach((marker) => { marker.setMap(null); }); markers = []; // For each place, get the icon, name and location. const bounds = new google.maps.LatLngBounds(); places.forEach((place) => { if (!place.geometry || !place.geometry.location) { console.log("Returned place contains no geometry"); return; } const icon = { 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), }; // Create a marker for each place. markers.push( new google.maps.Marker({ map, icon, title: place.name, position: place.geometry.location, }), ); if (place.geometry.viewport) { // Only geocodes have viewport. bounds.union(place.geometry.viewport); } else { bounds.extend(place.geometry.location); } }); map.fitBounds(bounds); });
Lihat Menata gaya widget Autocomplete dan SearchBox untuk menyesuaikan tampilan widget.
Mengambil prediksi Layanan Place Autocomplete secara terprogram
Untuk mengambil prediksi secara terprogram, gunakan class
AutocompleteService
. AutocompleteService
tidak menambahkan kontrol UI apa pun. Sebagai gantinya, class ini menampilkan array objek prediksi, yang masing-masing berisi teks prediksi, informasi referensi, dan detail tentang kecocokan hasil dengan input pengguna.
Hal ini berguna jika Anda menginginkan lebih banyak kontrol terhadap antarmuka pengguna daripada yang ditawarkan oleh Autocomplete
dan SearchBox
yang dijelaskan di atas.
AutocompleteService
mengekspos metode berikut:
getPlacePredictions()
menampilkan prediksi tempat. Catatan: Sebuah 'tempat' dapat berupa tempat usaha, lokasi geografis, atau lokasi menarik terkemuka, sebagaimana didefinisikan oleh Places API.getQueryPredictions()
menampilkan daftar prediksi tambahan, yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) dan istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza in new', daftar pilihan mungkin menyertakan frasa 'pizza in New York, NY' serta nama-nama berbagai gerai pizza.
Kedua metode di atas menampilkan array objek prediksi dengan bentuk berikut:
description
adalah prediksi yang cocok.distance_meters
adalah jarak tempat dalam meter dariAutocompletionRequest.origin
yang ditentukan.matched_substrings
berisi kumpulan substring dalam deskripsi yang cocok dengan elemen dalam input pengguna. Hal ini berguna untuk menyoroti substring tersebut dalam aplikasi Anda. Dalam banyak kasus, kueri akan muncul sebagai substring kolom deskripsi.length
adalah panjang substring.offset
adalah offset karakter, yang diukur dari awal string deskripsi, tempat substring yang cocok muncul.
place_id
adalah ID tekstual yang secara unik mengidentifikasi tempat. Untuk mengambil informasi tentang tempat, teruskan ID ini dalam kolomplaceId
pada permintaan Place Details. Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.terms
adalah array yang berisi elemen kueri. Untuk sebuah tempat, setiap elemen biasanya membentuk bagian alamat.offset
adalah offset karakter, yang diukur dari awal string deskripsi, tempat substring yang cocok muncul.value
adalah istilah yang cocok.
Contoh di bawah ini mengeksekusi permintaan prediksi kueri untuk frasa 'pizza near' dan menampilkan hasilnya dalam daftar.
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // 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 initService(): void { const displaySuggestions = function ( predictions: google.maps.places.QueryAutocompletePrediction[] | null, status: google.maps.places.PlacesServiceStatus ) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); (document.getElementById("results") as HTMLUListElement).appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } declare global { interface Window { initService: () => void; } } window.initService = initService;
JavaScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // 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 initService() { const displaySuggestions = function (predictions, status) { if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) { alert(status); return; } predictions.forEach((prediction) => { const li = document.createElement("li"); li.appendChild(document.createTextNode(prediction.description)); document.getElementById("results").appendChild(li); }); }; const service = new google.maps.places.AutocompleteService(); service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions); } window.initService = initService;
CSS
HTML
<html> <head> <title>Retrieving Autocomplete Predictions</title> <link rel="stylesheet" type="text/css" href="./style.css" /> <script type="module" src="./index.js"></script> </head> <body> <p>Query suggestions for 'pizza near Syd':</p> <ul id="results"></ul> <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements --> <img class="powered-by-google" src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png" alt="Powered by Google" /> <!-- The `defer` attribute causes the script to execute after the full HTML document has been parsed. For non-blocking uses, avoiding race conditions, and consistent behavior across browsers, consider loading using Promises. See https://developers.google.com/maps/documentation/javascript/load-maps-js-api for more information. --> <script src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly" defer ></script> </body> </html>
Mencoba Contoh
Token sesi
AutocompleteService.getPlacePredictions()
dapat menggunakan token sesi (jika diterapkan) untuk mengelompokkan permintaan pelengkapan otomatis untuk tujuan penagihan. Token sesi mengelompokkan fase kueri dan pemilihan dari penelusuran pelengkapan otomatis pengguna ke dalam sesi terpisah untuk tujuan penagihan. Sesi dimulai saat pengguna mulai mengetik kueri, dan berakhir saat memilih tempat. Setiap sesi dapat memiliki beberapa kueri, yang diikuti dengan satu pilihan tempat.
Setelah sesi selesai, token tidak lagi valid. Aplikasi Anda harus membuat token baru untuk setiap sesi. Sebaiknya gunakan token sesi untuk semua sesi pelengkapan otomatis. Jika parameter sessionToken
dihilangkan, atau jika Anda menggunakan kembali token sesi, sesi tersebut dikenai biaya seolah-olah tidak ada token sesi yang diberikan (setiap permintaan ditagih secara terpisah).
Anda dapat menggunakan token sesi yang sama untuk membuat satu permintaan Place Details di tempat yang dihasilkan dari panggilan ke AutocompleteService.getPlacePredictions()
.
Dalam hal ini, permintaan pelengkapan otomatis digabungkan dengan permintaan Place Details, dan panggilan dikenai biaya sebagai permintaan Place Details biasa. Permintaan Autocomplete
tidak dikenai biaya.
Pastikan untuk meneruskan token sesi yang unik untuk setiap sesi baru. Penggunaan token yang sama untuk lebih dari satu sesi Autocomplete akan membatalkan sesi Autocomplete tersebut, dan semua permintaan Autocomplete dalam sesi yang tidak valid akan ditagih satu per satu menggunakan SKU Autocomplete Per Request. Baca selengkapnya tentang token sesi.
Contoh berikut menunjukkan pembuatan token sesi, lalu meneruskannya dalam
AutocompleteService
(fungsi displaySuggestions()
telah dihilangkan agar lebih singkat):
// Create a new session token. var sessionToken = new google.maps.places.AutocompleteSessionToken(); // Pass the token to the autocomplete service. var autocompleteService = new google.maps.places.AutocompleteService(); autocompleteService.getPlacePredictions({ input: 'pizza near Syd', sessionToken: sessionToken }, displaySuggestions);
Pastikan untuk meneruskan token sesi yang unik untuk setiap sesi baru. Jika menggunakan token yang sama untuk lebih dari satu sesi, setiap permintaan akan ditagih satu per satu.
Baca selengkapnya tentang token sesi.
Menata gaya widget Autocomplete dan SearchBox
Secara default, elemen UI yang disediakan oleh Autocomplete
dan SearchBox
telah ditata untuk dimasukkan dalam peta Google. Anda mungkin perlu
menyesuaikan gaya dengan situs Anda sendiri. Tersedia class CSS
berikut. Semua class yang tercantum di bawah berlaku untuk widget Autocomplete
dan SearchBox
.
Class CSS | Deskripsi |
---|---|
pac-container |
Elemen visual berisi daftar prediksi yang ditampilkan oleh layanan Place Autocomplete. Daftar ini muncul sebagai daftar dropdown di bawah widget Autocomplete atau SearchBox . |
pac-icon |
Ikon yang ditampilkan di sebelah kiri setiap item dalam daftar prediksi. |
pac-item |
Item dalam daftar prediksi yang disediakan oleh widget Autocomplete atau SearchBox . |
pac-item:hover |
Item saat pengguna menempatkan kursor mouse di atasnya. |
pac-item-selected |
Item saat pengguna memilihnya melalui keyboard. Catatan: Item yang dipilih
akan menjadi anggota class ini dan class pac-item .
|
pac-item-query |
Span di dalam pac-item yang merupakan bagian utama dari prediksi. Untuk lokasi geografis, isinya adalah nama tempat, seperti 'Sydney', atau nama jalan dan nomor rumah, seperti '10 King Street'. Untuk penelusuran berbasis teks seperti 'pizza in New York', isinya adalah teks lengkap dari kueri. Secara default, pac-item-query warnanya hitam. Jika ada teks tambahan dalam pac-item , teks tersebut berada di luar pac-item-query dan mewarisi gayanya dari pac-item . Secara default, warnanya abu-abu. Teks tambahan biasanya berupa alamat. |
pac-matched |
Bagian dari prediksi yang ditampilkan sesuai dengan input pengguna. Secara default, teks yang cocok ini disorot dalam teks tebal. Perhatikan bahwa teks yang cocok dapat berada di mana saja dalam pac-item . Class ini
belum tentu bagian dari pac-item-query , dan bisa saja sebagian
dalam pac-item-query serta sebagian lagi dalam teks sisanya di pac-item . |
Pengoptimalan Place Autocomplete
Bagian ini menjelaskan praktik terbaik untuk membantu Anda memaksimalkan layanan Place Autocomplete.
Berikut ini beberapa pedoman umum:
- Cara tercepat untuk membuat antarmuka pengguna yang berfungsi baik adalah dengan menggunakan widget Autocomplete Maps JavaScript API, widget Autocomplete Places SDK for Android, atau Kontrol UI Autocomplete Places SDK for iOS
- Kembangkan pemahaman tentang kolom data Place Autocomplete yang penting sejak awal.
- Kolom pembiasan lokasi dan pembatasan lokasi bersifat opsional, tetapi dapat memberikan dampak signifikan terhadap performa pelengkapan otomatis.
- Gunakan penanganan error untuk memastikan aplikasi Anda terdegrasi secara halus jika API menampilkan error.
- Pastikan aplikasi Anda menanganinya jika tidak ada pilihan dan menawarkan cara kepada pengguna untuk melanjutkan.
Praktik terbaik pengoptimalan biaya
Pengoptimalan biaya dasar
Untuk mengoptimalkan biaya penggunaan layanan Place Autocomplete, gunakan mask kolom dalam widget Place Details dan Place Autocomplete agar hanya menampilkan kolom data tempat yang Anda butuhkan.
Pengoptimalan biaya lanjutan
Pertimbangkan implementasi Place Autocomplete yang terprogram untuk mengakses Harga Per Permintaan dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details. Harga Per Permintaan yang dipasangkan dengan Geocoding API lebih hemat biaya daripada harga Per Sesi (berbasis sesi) jika kondisi berikut terpenuhi:
- Jika Anda hanya memerlukan lintang/bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini dengan biaya yang lebih murah daripada panggilan Place Details.
- Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete atau kurang, harga Per Permintaan mungkin lebih hemat biaya daripada harga Per Sesi.
Apakah aplikasi Anda memerlukan informasi selain alamat dan lintang/bujur dari prediksi yang dipilih?
Ya, memerlukan informasi lebih detail
Gunakan Place Autocomplete berbasis sesi dengan Place Details.
Karena aplikasi Anda memerlukan Place Details seperti nama tempat, status bisnis, atau jam buka, penerapan Place Autocomplete harus menggunakan token sesi (secara terprogram atau diintegrasikan ke widget JavaScript, Android, atau iOS) dengan total biaya sebesar $0,017 per sesi ditambah SKU Data Places yang relevan, bergantung pada kolom data tempat yang Anda minta.1
Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget JavaScript, Android, atau iOS. Ini mencakup permintaan Place Autocomplete dan permintaan Place Details pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields
untuk memastikan Anda hanya meminta
kolom data tempat yang Anda butuhkan.
Penerapan terprogram
Gunakan token sesi dengan permintaan Place Autocomplete Anda. Saat meminta Place Details tentang prediksi yang dipilih, sertakan parameter berikut:
- ID tempat dari respons Place Autocomplete
- Token sesi yang digunakan dalam permintaan Place Autocomplete
- Parameter
fields
yang menentukan kolom data tempat yang Anda perlukan
Tidak, hanya memerlukan alamat dan lokasi
Geocoding API dapat menjadi opsi yang lebih hemat biaya daripada Place Details untuk aplikasi Anda, bergantung pada performa penggunaan Place Autocomplete. Efisiensi Autocomplete setiap aplikasi bervariasi bergantung pada apa yang dimasukkan oleh pengguna, tempat aplikasi digunakan, dan apakah praktik terbaik pengoptimalan performa telah diterapkan.
Untuk menjawab pertanyaan berikut, analisis rata-rata jumlah karakter yang diketik pengguna sebelum memilih prediksi Place Autocomplete di aplikasi Anda.
Apakah pengguna Anda rata-rata memilih prediksi Place Autocomplete dalam empat permintaan atau kurang?
Ya
Terapkan Place Autocomplete secara terprogram tanpa token sesi dan panggil Geocoding API di prediksi tempat yang dipilih.
Geocoding API memberikan alamat dan koordinat lintang/bujur dengan biaya sebesar $0,005 per permintaan. Membuat empat permintaan Place Autocomplete - Per Permintaan dikenai biaya $0,01132 sehingga total biaya empat permintaan ditambah panggilan Geocoding API tentang prediksi tempat yang dipilih adalah $0,01632, yang lebih rendah daripada harga Autocomplete - Per Session, yaitu $0,017 per sesi.1
Pertimbangkan untuk menerapkan praktik terbaik performa guna membantu pengguna mendapatkan prediksi yang mereka cari dengan lebih sedikit karakter.
Tidak
Gunakan Place Autocomplete berbasis sesi dengan Place Details.
Karena jumlah rata-rata permintaan yang harus Anda buat sebelum pengguna memilih prediksi Place Autocomplete akan melebihi biaya harga Per Sesi, penerapan Place Autocomplete harus menggunakan token sesi untuk permintaan Place Autocomplete dan permintaan Place Details yang terkait, dengan total biaya sebesar $0,017 per sesi.1
Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget JavaScript, Android, atau iOS. Ini mencakup permintaan Place Autocomplete dan permintaan Place Details pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields
untuk memastikan Anda hanya meminta kolom Basic Data.
Penerapan terprogram
Gunakan token sesi dengan permintaan Place Autocomplete Anda. Saat meminta Place Details tentang prediksi yang dipilih, sertakan parameter berikut:
- ID tempat dari respons Place Autocomplete
- Token sesi yang digunakan dalam permintaan Place Autocomplete
- Parameter
fields
yang menentukan kolom Basic Data seperti alamat dan geometri
Pertimbangkan untuk menunda permintaan Place Autocomplete
Anda dapat menggunakan strategi seperti menunda permintaan Place Autocomplete hingga pengguna mengetik tiga atau empat karakter pertama, sehingga aplikasi Anda membuat lebih sedikit permintaan. Misalnya, membuat permintaan Place Autocomplete untuk setiap karakter setelah pengguna mengetik karakter ketiga berarti jika pengguna mengetik tujuh karakter, lalu memilih prediksi yang telah Anda buatkan untuknya satu permintaan Geocoding API, biaya total akan menjadi $0,01632 (4 * $0,00283 Autocomplete Per Request + $0,005 Geocoding).1
Jika permintaan yang tertunda dapat menghasilkan permintaan terprogram rata-rata di bawah empat, Anda dapat mengikuti panduan ini untuk penerapan Place Autocomplete yang berperforma dengan Geocoding API. Perhatikan bahwa permintaan yang tertunda dapat dianggap sebagai latensi oleh pengguna yang mungkin berharap melihat prediksi dengan setiap karakter baru yang mereka ketik.
Pertimbangkan untuk menerapkan praktik terbaik performa guna membantu pengguna Anda mendapatkan prediksi yang mereka cari dengan lebih sedikit karakter.
-
Biaya yang tercantum di sini adalah dalam USD. Lihat halaman Billing di Google Maps Platform untuk mendapatkan informasi harga selengkapnya.
Praktik terbaik performa
Panduan berikut menjelaskan cara mengoptimalkan performa Place Autocomplete:
- Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Place Autocomplete Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
- Jika Place Autocomplete disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
- Jika pengguna tidak memilih salah satu prediksi Autocomplete, umumnya karena tidak satu pun prediksi tersebut yang merupakan alamat hasil yang diinginkan, Anda dapat menggunakan kembali input pengguna yang asli untuk mendapatkan hasil yang lebih relevan:
- Jika Anda mengharapkan pengguna hanya memasukkan informasi alamat, gunakan kembali input pengguna yang asli dalam panggilan ke Geocoding API.
- Jika Anda memperkirakan pengguna akan memasukkan kueri untuk tempat tertentu berdasarkan nama atau alamat, gunakan permintaan Find Place. Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
- Pengguna memasukkan alamat subpremis di negara yang tidak memiliki dukungan lengkap untuk Place Autocomplete, misalnya Republik Ceko, Estonia, dan Lituania. Misalnya, alamat Ceko "Stroupežnického 3191/17, Praha" akan menghasilkan prediksi parsial di Place Autocomplete.
- Pengguna memasukkan alamat dengan awalan segmen jalan seperti "23-30 29th St, Queens" di New York City atau "47-380 Kamehameha Hwy, Kaneohe" di pulau Kauai di Hawai'i.
Kebijakan dan batas penggunaan
Kuota
Untuk informasi kuota dan harga, lihat dokumentasi Penggunaan dan Penagihan untuk Places API.
Kebijakan
Penggunaan Places Library, Maps JavaScript API harus sesuai dengan kebijakan yang dijelaskan untuk Places API.