Autocomplete (Baru) menampilkan prediksi tempat sebagai respons terhadap permintaan yang menyertakan string penelusuran teks dan batas geografis yang mengontrol area penelusuran. Autocomplete dapat mencocokkan kata lengkap dan substring input, yang me-resolve nama tempat, alamat, dan Plus Codes. Aplikasi Anda dapat mengirim kueri saat pengguna mengetik, untuk memberikan prediksi tempat dan kueri secara real time.
Misalnya, Anda memanggil Autocomplete menggunakan string sebagai input yang berisi input pengguna sebagian, "Sicilian piz", dengan area penelusuran terbatas pada San Francisco, CA. Respons kemudian berisi daftar prediksi tempat yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Sicilian Pizza Kitchen".
Prediksi tempat yang ditampilkan didesain untuk disajikan kepada pengguna guna membantu mereka dalam memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (New) untuk mendapatkan informasi selengkapnya tentang prediksi tempat yang ditampilkan.
Permintaan Autocomplete (Baru)
Aplikasi Anda bisa mendapatkan daftar nama tempat dan/atau alamat yang diprediksi dari API pelengkapan otomatis dengan memanggil PlacesClient.findAutocompletePredictions()
, yang meneruskan objek FindAutocompletePredictionsRequest
. Contoh di bawah menunjukkan panggilan lengkap ke
PlacesClient.findAutocompletePredictions()
.
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Sicilian piz") .setRegionCode("ES") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Respons Autocomplete (Baru)
API menampilkan
FindAutocompletePredictionsResponse
dalam
Task
.
FindAutocompletePredictionsResponse
berisi daftar hingga lima objek AutocompletePrediction
yang mewakili tempat yang diprediksi. Daftar mungkin kosong, jika tidak ada
tempat yang diketahui sesuai dengan kueri dan kriteria filter.
Untuk setiap tempat yang diprediksi, Anda dapat memanggil metode berikut untuk mengambil detail tempat:
getFullText(CharacterStyle)
menampilkan teks lengkap deskripsi tempat. Ini adalah kombinasi dari teks utama dan sekunder. Contoh: "Eiffel Tower, Avenue Anatole France, Paris, France". Selain itu, metode ini memungkinkan Anda menyoroti bagian deskripsi yang cocok dengan penelusuran dengan gaya pilihan Anda, menggunakanCharacterStyle
. ParameterCharacterStyle
bersifat opsional. Tetapkan ke null jika Anda tidak memerlukan penyoratan apa pun.getPrimaryText(CharacterStyle)
menampilkan teks utama yang menjelaskan tempat. Ini biasanya adalah nama tempat. Contoh: "Menara Eiffel", dan "123 Pitt Street".getSecondaryText(CharacterStyle)
menampilkan teks pendukung dari deskripsi tempat. Hal ini berguna, misalnya, sebagai baris kedua saat menampilkan prediksi pelengkapan otomatis. Contoh: "Avenue Anatole France, Paris, France", dan "Sydney, New South Wales".getPlaceId()
menampilkan ID tempat untuk tempat yang diprediksi. ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat, yang dapat Anda gunakan untuk mengambil objekPlace
lagi nanti. Untuk informasi selengkapnya tentang ID tempat di Autocomplete, lihat Place Details (New). Untuk informasi umum tentang ID tempat, lihat Ringkasan ID tempat.getTypes()
menampilkan daftar jenis tempat yang terkait dengan tempat ini.getDistanceMeters()
menampilkan jarak garis lurus dalam meter antara tempat ini dan asal yang ditentukan dalam permintaan.
Parameter wajib
-
Kueri
String teks yang digunakan untuk menelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan Plus Codes. Layanan Autocomplete (Baru) menampilkan kandidat hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.
Untuk menetapkan parameter kueri, panggil metode
setQuery()
saat mem-build objekFindAutocompletePredictionsRequest
.
Parameter opsional
-
Jenis utama
Daftar hingga lima nilai jenis dari jenis Tabel A atau Tabel B yang digunakan untuk memfilter tempat yang ditampilkan dalam respons. Tempat harus cocok dengan salah satu nilai jenis utama yang ditentukan agar disertakan dalam respons.
Tempat hanya dapat memiliki satu jenis utama dari jenis Tabel A atau Tabel B yang terkait dengannya. Misalnya, jenis utama mungkin
"mexican_restaurant"
atau"steak_house"
.Permintaan ditolak dengan error
INVALID_REQUEST
jika:- Lebih dari lima jenis ditentukan.
- Semua jenis yang tidak dikenal ditentukan.
Untuk menetapkan parameter jenis utama, panggil metode
setTypesFilter()
saat mem-build objekFindAutocompletePredictionsRequest
. -
Negara
Hanya sertakan hasil dari daftar negara yang ditentukan, yang ditentukan sebagai daftar hingga 15 nilai dua karakter ccTLD ("domain level teratas"). Jika dihilangkan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi wilayah ke Jerman dan Prancis:
Jika Anda menentukan
locationRestriction
danincludedRegionCodes
, hasilnya akan berada di area persimpangan kedua setelan tersebut.Untuk menetapkan parameter negara, panggil metode
setCountries()
saat mem-build objekFindAutocompletePredictionsRequest
. -
Offset input
Offset karakter Unicode berbasis nol yang menunjukkan posisi kursor dalam kueri. Posisi kursor dapat memengaruhi prediksi yang ditampilkan. Jika kosong, nilai defaultnya adalah panjang kueri.
Untuk menetapkan parameter offset input, panggil metode
setInputOffset()
saat mem-build objekFindAutocompletePredictionsRequest
. Bias lokasi atau pembatasan lokasi
Anda dapat menentukan bias lokasi atau batasan lokasi, tetapi tidak keduanya, untuk menentukan area penelusuran. Anggap pembatasan lokasi sebagai menentukan wilayah tempat hasil harus berada, dan bias lokasi sebagai menentukan wilayah tempat hasil harus berada di dekatnya. Perbedaan utamanya adalah bahwa dengan bias lokasi, hasil di luar wilayah yang ditentukan mungkin masih ditampilkan.
Bias lokasi
Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias, bukan batasan, sehingga hasil di luar area yang ditentukan mungkin masih ditampilkan.
Untuk menetapkan parameter bias lokasi, panggil metode
setLocationBias()
saat mem-build objekFindAutocompletePredictionsRequest
.Pembatasan lokasi
Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak ditampilkan.
Untuk menetapkan parameter pembatasan lokasi, panggil metode
setLocationRestriction()
saat mem-build objekFindAutocompletePredictionsRequest
.
Tentukan bias lokasi atau wilayah pembatasan lokasi sebagai Area Tampilan persegi panjang atau sebagai lingkaran.
Lingkaran ditentukan oleh titik tengah dan radius dalam meter. Radius harus antara 0,0 dan 50000,0, inklusif. Nilai defaultnya adalah 0,0. Untuk pembatasan lokasi, Anda harus menetapkan radius ke nilai yang lebih besar dari 0,0. Jika tidak, permintaan tidak akan menampilkan hasil.
Persegi panjang adalah area pandang lintang-bujur, yang direpresentasikan sebagai dua titik
low
danhigh
yang berlawanan secara diagonal. Area pandang dianggap sebagai wilayah tertutup, yang berarti mencakup batasnya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat inklusif:- Jika
low
=high
, area pandang terdiri dari satu titik tersebut. - Jika
low.longitude
>high.longitude
, rentang bujur akan terbalik (area pandang melintasi garis bujur 180 derajat). - Jika
low.longitude
= -180 derajat danhigh.longitude
= 180 derajat, area pandang akan menyertakan semua bujur. - Jika
low.longitude
= 180 derajat danhigh.longitude
= -180 derajat, rentang bujur akan kosong.
low
danhigh
harus diisi, dan kotak yang direpresentasikan tidak boleh kosong. Area pandang kosong akan menyebabkan error.- Jika
-
Asal
Titik asal tempat jarak garis lurus dihitung ke tujuan (diakses menggunakan
getDistanceMeters()
). Jika nilai ini dihilangkan, jarak garis lurus tidak akan ditampilkan. Harus ditentukan sebagai koordinat lintang dan bujur:Untuk menetapkan parameter origin, panggil metode
setOrigin()
saat mem-build objekFindAutocompletePredictionsRequest
. -
Kode wilayah
Kode wilayah yang digunakan untuk memformat respons, termasuk pemformatan alamat, yang ditentukan sebagai nilai dua karakter ccTLD ("domain level teratas"). Sebagian besar kode ccTLD identik dengan kode ISO 3166-1, dengan beberapa pengecualian. Misalnya, ccTLD Inggris Raya adalah "uk" (.co.uk) sedangkan kode ISO 3166-1-nya adalah "gb" (secara teknis untuk entitas "The United Kingdom of Great Britain and Northern Ireland").
Jika Anda menentukan kode wilayah yang tidak valid, API akan menampilkan error
INVALID_ARGUMENT
. Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.Untuk menetapkan parameter kode wilayah, panggil metode
setRegionCode()
saat mem-build objekFindAutocompletePredictionsRequest
. -
Token sesi
Token sesi adalah string buatan pengguna yang melacak panggilan Autocomplete (Baru) sebagai "sesi". Pelengkapan otomatis menggunakan token sesi untuk 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 terprogram (saat Anda menyematkan fragmen, atau meluncurkan pelengkapan otomatis menggunakan intent, API akan menanganinya secara otomatis).
Autocomplete menggunakan
AutocompleteSessionToken
untuk mengidentifikasi setiap sesi. Aplikasi Anda harus meneruskan token sesi baru saat memulai setiap sesi baru, lalu meneruskan token yang sama, beserta ID Tempat, dalam panggilan berikutnya kefetchPlace()
untuk mengambil Place Details untuk tempat yang dipilih oleh pengguna.Untuk menetapkan parameter token sesi, panggil metode
setSessionToken()
saat mem-build objekFindAutocompletePredictionsRequest
.Untuk mengetahui informasi selengkapnya, lihat Token sesi.
Contoh Autocomplete (Baru)
Menggunakan pembatasan lokasi dan bias lokasi
Autocomplete (Baru) menggunakan bias IP secara default untuk mengontrol area penelusuran. Dengan bias IP, API menggunakan alamat IP perangkat untuk membiaskan hasil. Anda dapat menggunakan pembatasan lokasi atau bias lokasi secara opsional, tetapi tidak keduanya, untuk menentukan area yang akan ditelusuri.
Pembatasan lokasi menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak akan ditampilkan. Contoh berikut menggunakan batasan lokasi untuk membatasi permintaan ke batasan lokasi melingkar dengan radius 5.000 meter yang berpusat di San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Dengan bias lokasi, lokasi berfungsi sebagai bias yang berarti hasil di sekitar lokasi yang ditentukan dapat ditampilkan, termasuk hasil di luar area yang ditentukan. Contoh berikutnya mengubah permintaan sebelumnya untuk menggunakan bias lokasi:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Menggunakan jenis utama
Gunakan parameter jenis utama untuk membatasi hasil dari permintaan agar berupa jenis tertentu seperti yang tercantum dalam Tabel A dan Tabel B. Anda dapat menentukan array hingga lima nilai. Jika dihilangkan, semua jenis akan ditampilkan.
Contoh berikut menentukan string kueri "Sepak Bola" dan menggunakan parameter jenis
utama untuk membatasi hasil ke tempat usaha jenis
"sporting_goods_store"
:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); final List<Place.Field> primaryTypes = Arrays.asList("sporting_goods_store"); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Soccer") .setIncludedPrimaryTypes(primaryTypes) .setLocationBias(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Jika Anda menghilangkan parameter jenis utama, hasilnya dapat menyertakan tempat
dari jenis yang mungkin tidak Anda inginkan, seperti "athletic_field"
.
Menggunakan origin
Saat Anda menyertakan parameter origin dalam permintaan, yang ditentukan sebagai koordinat lintang dan bujur, API akan menyertakan jarak garis lurus dari asal ke tujuan dalam respons (diakses menggunakan getDistanceMeters()
). Contoh ini menetapkan asal ke pusat San Francisco:
Places.initializeWithNewPlacesApiEnabled(context, apiKey); final List<Field> placeFields = getPlaceFields(); LatLng center = new LatLng(37.7749, -122.4194); CircularBounds circle = CircularBounds.newInstance(center, /* radius = */ 5000); final FindAutocompletePredictionsRequest autocompletePlacesRequest = FindAutocompletePredictionsRequest.builder() .setQuery("Amoeba") .setOrigin(center) .setLocationRestriction(circle) .build()); placesClient.findAutocompletePredictions(autoCompletePlacesRequest) .addOnSuccessListener( (response) -> { List<AutocompletePrediction> predictions = response.getResult().getAutocompletePredictions(); } ).addOnFailureListener( exception -> { Log.e(TAG, "some exception happened" + exception.getMessage()); }) );
Atribusi
Anda dapat menggunakan Autocomplete (Baru) meskipun tanpa peta. Jika Anda menampilkan peta, peta tersebut harus berupa peta Google. Saat menampilkan prediksi dari layanan Autocomplete (Baru) tanpa peta, Anda harus menyertakan logo Google yang ditampilkan secara inline dengan kolom/hasil penelusuran. Untuk mengetahui informasi selengkapnya, lihat Menampilkan logo dan atribusi Google.