Autocomplete (Baru) menampilkan prediksi tempat sebagai respons terhadap permintaan yang mencakup string penelusuran teks dan batas geografis yang mengontrol area penelusuran. Autocomplete dapat mencocokkan kata dan substring lengkap dari input, yang me-resolve nama tempat, alamat, dan Plus Codes. Aplikasi Anda dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat dan kueri secara real time.
Misalnya, Anda memanggil Autocomplete menggunakan input string yang berisi input pengguna sebagian, "pizza Sisilia", dengan area penelusuran terbatas di 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 dirancang untuk ditampilkan kepada pengguna guna membantu mereka memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (Baru) untuk mendapatkan informasi selengkapnya tentang prediksi tempat yang ditampilkan.
Anda dapat mengintegrasikan fungsi Pelengkapan Otomatis (Baru) ke dalam aplikasi Anda dengan dua cara utama:
- Menambahkan widget Place Autocomplete:
Menyediakan pengalaman pelengkapan otomatis penelusuran yang siap digunakan melalui class
PlaceAutocomplete
yang menampilkan prediksi saat pengguna mengetik. - Mendapatkan prediksi tempat secara terprogram: Panggil API secara langsung untuk mengambil prediksi dan menampilkannya di antarmuka pengguna kustom.
Menambahkan widget Place Autocomplete
Untuk memberikan pengalaman pelengkapan otomatis tempat yang konsisten dengan lebih mudah, Anda dapat menambahkan widget Place Autocomplete ke aplikasi Anda. Widget ini menyediakan antarmuka layar penuh khusus yang menangani input pengguna dan menampilkan prediksi tempat kepada pengguna sekaligus menampilkan objek AutocompletePrediction
ke aplikasi. Kemudian, Anda dapat membuat permintaan Place Details (Baru) untuk mendapatkan informasi tambahan tentang prediksi tempat.
Seperti saat mendapatkan prediksi tempat secara terprogram,
widget Place Autocomplete memungkinkan Anda menggunakan
token sesi untuk mengelompokkan permintaan pelengkapan otomatis ke dalam sesi
untuk tujuan penagihan. Anda dapat meneruskan token sesi saat membuat intent untuk
widget dengan memanggil setAutocompleteSessionToken()
. Jika Anda tidak memberikan token sesi, widget akan membuatnya untuk Anda, yang dapat Anda akses dengan memanggil getSessionTokenFromIntent()
. Untuk mengetahui informasi selengkapnya tentang cara menggunakan token sesi, lihat Tentang token sesi.
Untuk menambahkan widget Place Autocomplete ke aplikasi Anda:
(Opsional) Tentukan token sesi. Jika Anda tidak memberikan token sesi, widget akan membuatnya untuk Anda.
Tentukan
autocompleteIntent
dengan parameter yang diinginkan dan token sesi Anda.Tentukan
ActivityResultLauncher
untukStartActivityForResult
. Peluncur ini akan menangani hasil yang ditampilkan dari aktivitas pelengkapan otomatis.Tangani hasilnya di callback
ActivityResultLauncher
. Hal ini melibatkan ekstraksiAutocompletePrediction
danAutocompleteSessionToken
(jika Anda belum menyediakannya), penanganan error, dan secara opsional membuat permintaanfetchPlace()
untuk mendapatkan detail tambahan tentang suatu tempat.Luncurkan intent menggunakan
placeAutocompleteActivityResultLauncher
Contoh berikut menunjukkan cara menambahkan widget Place Autocomplete menggunakan Kotlin dan Java:
Kotlin
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key) // Optional, create a session token for Autocomplete request and the followup FetchPlace request. val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance() val autocompleteIntent: Intent = PlaceAutocomplete.createIntent(this) { // ... provide input params for origin, countries, types filter ... setAutocompleteSessionToken(sessionToken) } val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> = registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult -> val intent = result.data if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object val prediction: AutocompletePrediction? = PlaceAutocomplete.getPredictionFromIntent(intent!!) // get session token val sessionToken: AutocompleteSessionToken? = PlaceAutocomplete.getSessionTokenFromIntent(intent!!) // create PlacesClient to make FetchPlace request (optional) val placesClient: PlacesClient = Places.createClient(this) val response = placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME) { sessionToken = sessionToken // optional } } } // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)
Java
// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console. Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key); // Optional, create a session token for Autocomplete request and the followup FetchPlace request AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance(); Intent autocompleteIntent = new PlaceAutocomplete.IntentBuilder() // ... set input params for origin, countries, types filter ... .setSessionToken(sessionToken) // optional .build(this); ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher = registerForActivityResult( new ActivityResultContracts.StartActivityForResult(), new ActivityResultCallback<ActivityResult>() { @Override public void onActivityResult(ActivityResult result) { Intent intent = result.getData(); if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) { // get prediction object AutocompletePrediction prediction = PlaceAutocomplete.getPredictionFromIntent( Preconditions.checkNotNull(intent)); // get session token AutocompleteSessionToken sessionToken = PlaceAutocomplete.getSessionTokenFromIntent( Preconditions.checkNotNull(intent)); // create PlacesClient to make FetchPlace request (optional) PlacesClient placesClient = Places.createClient(this); FetchPlaceRequest request = FetchPlaceRequest.builder(prediction.getPlaceId(), Arrays.asList(Field.DISPLAY_NAME)) .setSessionToken(sessionToken).build(); Task<FetchPlaceResponse> task = placesClient.fetchPlace(request); } } } ); // Launch Activity placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);
Mendapatkan prediksi tempat secara terprogram
Aplikasi Anda dapat memperoleh daftar nama dan/atau alamat tempat yang diprediksi dari
API pelengkapan otomatis dengan memanggil
PlacesClient.findAutocompletePredictions()
,
dengan 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 Pelengkapan Otomatis (Baru)
API menampilkan
FindAutocompletePredictionsResponse
dalam
Task
.
FindAutocompletePredictionsResponse
berisi daftar hingga lima
objek AutocompletePrediction
yang merepresentasikan 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: "Menara Eiffel, Avenue Anatole France, Paris, Prancis". Selain itu, metode ini memungkinkan Anda menandai bagian deskripsi yang cocok dengan penelusuran menggunakan gaya pilihan Anda, denganCharacterStyle
. ParameterCharacterStyle
bersifat opsional. Tetapkan ke null jika Anda tidak memerlukan penyorotan.getPrimaryText(CharacterStyle)
menampilkan teks utama yang mendeskripsikan suatu tempat. Ini biasanya adalah nama tempat. Contoh: "Menara Eiffel", dan "123 Pitt Street".getSecondaryText(CharacterStyle)
menampilkan teks tambahan dari deskripsi tempat. Hal ini berguna, misalnya, sebagai baris kedua saat menampilkan prediksi pelengkapan otomatis. Contoh: "Avenue Anatole France, Paris, Prancis", dan "Sydney, New South Wales".getPlaceId()
menampilkan ID tempat dari tempat yang diprediksi. ID tempat adalah ID tekstual yang secara unik mengidentifikasi tempat, yang dapat Anda gunakan untuk mengambil objekPlace
lagi nanti. Untuk mengetahui informasi selengkapnya tentang ID tempat di Autocomplete, lihat Place Details (Baru). 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 akan ditelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan Plus Codes. Layanan Pelengkapan Otomatis (Baru) menampilkan bakal hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.
Untuk menetapkan parameter kueri, panggil metode
setQuery()
saat membuat 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.
Suatu 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.
- Jenis yang tidak dikenal akan ditentukan.
Untuk menetapkan parameter jenis utama, panggil metode
setTypesFilter()
saat membuat objekFindAutocompletePredictionsRequest
. -
Negara
Hanya sertakan hasil dari daftar negara yang ditentukan, yang ditetapkan sebagai daftar hingga 15 nilai dua karakter ccTLD ("domain level teratas"). Jika tidak disertakan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi wilayah ke Jerman dan Prancis:
Jika Anda menentukan
locationRestriction
danincludedRegionCodes
, hasilnya terletak di area persimpangan kedua setelan.Untuk menetapkan parameter negara, panggil metode
setCountries()
saat membuat objekFindAutocompletePredictionsRequest
. -
Offset input
Offset karakter Unicode berbasis nol yang menunjukkan posisi kursor dalam kueri. Posisi kursor dapat memengaruhi prediksi yang ditampilkan. Jika kosong, defaultnya adalah panjang kueri.
Untuk menetapkan parameter offset input, panggil metode
setInputOffset()
saat membangun 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 penentuan region tempat hasil harus berada, dan bias lokasi sebagai penentuan region tempat hasil harus berada di dekatnya. Perbedaan utamanya adalah dengan bias lokasi, hasil di luar wilayah yang ditentukan mungkin tetap ditampilkan.
Bias lokasi
Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias, bukan batasan, sehingga hasil di luar area yang ditentukan mungkin tetap ditampilkan.
Untuk menyetel parameter bias lokasi, panggil metode
setLocationBias()
saat membangun 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 membuat objekFindAutocompletePredictionsRequest
.
Tentukan bias lokasi atau wilayah pembatasan lokasi sebagai Viewport 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 berada dalam rentang -90 hingga 90 derajat inklusif, dan batas bujur harus berada dalam rentang -180 hingga 180 derajat inklusif:- Jika
low
=high
, area tampilan terdiri dari satu titik tersebut. - Jika
low.longitude
>high.longitude
, rentang bujur akan dibalik (area pandang melintasi garis bujur 180 derajat). - Jika
low.longitude
= -180 derajat danhigh.longitude
= 180 derajat, area pandang mencakup semua bujur. - Jika
low.longitude
= 180 derajat danhigh.longitude
= -180 derajat, rentang bujur kosong.
low
danhigh
harus diisi, dan kotak yang ditampilkan tidak boleh kosong. Viewport kosong akan menyebabkan error.- Jika
-
Asal
Titik asal untuk menghitung jarak garis lurus ke tujuan (diakses menggunakan
getDistanceMeters()
). Jika nilai ini tidak ada, jarak garis lurus tidak akan ditampilkan. Harus ditentukan sebagai koordinat lintang dan bujur:Untuk menyetel parameter asal, panggil metode
setOrigin()
saat membuat 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 dapat memengaruhi hasil berdasarkan hukum yang berlaku.Untuk menetapkan parameter kode wilayah, panggil metode
setRegionCode()
saat membuat objekFindAutocompletePredictionsRequest
. -
Token sesi
Token sesi adalah string yang dibuat pengguna yang melacak panggilan Autocomplete (Baru)—baik panggilan yang dilakukan melalui widget maupun panggilan terprogram—sebagai "sesi". Autocomplete 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 Detail Tempat untuk tempat yang dipilih oleh pengguna.Untuk menetapkan parameter token sesi, panggil metode
setSessionToken()
saat membuat objekFindAutocompletePredictionsRequest
.Untuk mengetahui informasi selengkapnya, lihat Token sesi.
Contoh Pelengkapan Otomatis (Baru)
Menggunakan pembatasan lokasi dan preferensi lokasi
Autocomplete (Baru) menggunakan penyesuaian IP secara default untuk mengontrol area penelusuran. Dengan penyesuaian IP, API menggunakan alamat IP perangkat untuk menyesuaikan hasil. Anda dapat secara opsional menggunakan pembatasan lokasi atau bias lokasi, 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 pembatasan lokasi untuk membatasi permintaan ke pembatasan 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 primary types untuk membatasi hasil dari permintaan agar berjenis 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 "Soccer" dan menggunakan parameter jenis utama untuk membatasi hasil ke tempat dengan 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 mencakup tempat
dengan jenis yang mungkin tidak Anda inginkan, seperti "athletic_field"
.
Gunakan asal
Saat Anda menyertakan parameter origin dalam permintaan, yang ditentukan sebagai
koordinat garis lintang dan bujur, API akan menyertakan jarak garis lurus
dari asal ke tujuan dalam respons (dapat 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 Pelengkapan Otomatis (Baru) meskipun tanpa peta. Jika Anda menampilkan peta, peta tersebut harus berupa peta Google. Saat Anda menampilkan prediksi dari layanan Pelengkapan Otomatis (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.