Pelengkapan Otomatis (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

Autocomplete (Baru) menampilkan prediksi tempat di merespons permintaan yang menyertakan string penelusuran teks dan batas geografis yang mengontrol area pencarian. Pelengkapan otomatis dapat cocok pada kata-kata dan substring lengkap dari input, me-resolve nama tempat, alamat, dan kode plus. Aplikasi Anda dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi kueri dan tempat dengan cepat.

Misalnya, Anda memanggil Autocomplete menggunakan string yang berisi sebagian input pengguna, "Sicilian piz", dengan area penelusuran yang terbatas untuk San Francisco, CA. Responsnya kemudian berisi daftar tempat prediksi yang cocok dengan string penelusuran dan area penelusuran, seperti restoran bernama "Dapur Pizza Sisilia".

Prediksi tempat yang dikembalikan dirancang untuk disajikan kepada pengguna untuk membantu mereka dalam memilih tempat yang diinginkan. Anda dapat membuat Place Details (Baru) untuk mendapatkan lebih banyak permintaan informasi tentang prediksi tempat yang dikembalikan.

Catatan: Autocomplete (Baru) tersedia di Places SDK untuk Android versi 3.5.0 dan yang lebih baru. Untuk informasi selengkapnya, lihat Memilih SDK Anda versi.

Permintaan Autocomplete (Baru)

Aplikasi Anda bisa mendapatkan daftar prediksi nama tempat dan/atau dari API pelengkapan otomatis dengan memanggil PlacesClient.findAutocompletePredictions(), meneruskan FindAutocompletePredictionsRequest . Contoh di bawah ini menunjukkan panggilan lengkap untuk 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());
        })
    );

Catatan: Panggilan yang dilakukan menggunakan Place Autocomplete widget selalu panggil Place Autocomplete, bukan Place Autocomplete (Baru); tidak terpengaruh oleh metode inisialisasi.

Catatan: Untuk informasi selengkapnya tentang melakukan inisialisasi PlacesClient, lihat Melakukan inisialisasi klien Places API.

Anda dapat menggunakan CancellationToken mencoba membatalkan permintaan ke class permintaan mana pun (misalnya, FetchPlaceRequest). Pembatalan dilakukan berdasarkan upaya terbaik. Setelah permintaan pembatalan diajukan, tidak ada respons yang akan dikembalikan. Menerbitkan token pembatalan TIDAK menjamin bahwa permintaan tertentu akan dibatalkan, dan Anda mungkin tetap dikenai biaya atas permintaan meskipun tidak ada respons yang ditampilkan.

Respons Autocomplete (Baru)

API menampilkan FindAutocompletePredictionsResponse di Task. Tujuan FindAutocompletePredictionsResponse berisi daftar hingga lima AutocompletePrediction objek yang merepresentasikan tempat yang diprediksi. Daftar ini mungkin kosong, jika tidak ada tempat yang diketahui sesuai dengan kueri dan kriteria filter.

Untuk setiap tempat yang diprediksi, Anda bisa memanggil metode berikut untuk mengambil tempat detail:

• getFullText(CharacterStyle) menampilkan teks lengkap dari deskripsi tempat. Ini adalah kombinasi dari teks utama dan sekunder. Contoh: "Menara Eiffel, Avenue Anatole France, Paris, Prancis". Selain itu, metode ini memungkinkan Anda menyoroti bagian deskripsi yang cocok dengan penelusuran dengan gaya pilihan Anda, menggunakan CharacterStyle. Parameter CharacterStyle bersifat opsional. Tetapkan ke null jika Anda tidak perlu sorotan apa pun.
• getPrimaryText(CharacterStyle) menampilkan teks utama yang mendeskripsikan tempat. Biasanya ini adalah nama dari saat ini. Contoh: "Eiffel Tower", dan "123 Pitt Street".
• getSecondaryText(CharacterStyle) menampilkan teks anak perusahaan dari deskripsi tempat. Hal ini berguna, karena misalnya, sebagai baris kedua saat menampilkan prediksi pelengkapan otomatis. Contoh: "Astreet Anatole France, Paris, France", dan "Sydney, New South Wales".
• getPlaceId() menampilkan ID tempat dari tempat yang diprediksi. ID tempat adalah tekstual yang secara unik mengidentifikasi tempat, yang bisa Anda gunakan untuk mengambil tindakan Place objek lagi nanti. Untuk informasi selengkapnya tentang ID tempat di Autocomplete, lihat Place Details (Baru). Untuk umum informasi tentang ID tempat, lihat ID Tempat ringkasan.
• getTypes() menampilkan daftar jenis tempat yang terkait dengan tempat ini.
• getDistanceMeters() mengembalikan jarak garis lurus dalam meter antara tempat ini dan origin yang ditentukan dalam permintaan.

Parameter wajib

• Kueri

  String teks yang akan ditelusuri. Tentukan kata-kata lengkap dan {i>substring<i}, nama tempat, alamat, dan plus code. Layanan Autocomplete (Baru) mengembalikan kandidat berdasarkan {i>string <i}ini dan mengurutkan hasil berdasarkan relevansi yang mereka rasakan.

  Untuk menetapkan parameter kueri, panggil setQuery() saat membangun objek FindAutocompletePredictionsRequest.

Parameter opsional

• Jenis utama

  Daftar yang berisi hingga lima nilai jenis dari berbagai Tabel A atau Tabel B digunakan untuk memfilter tempat yang ditampilkan dalam respons. Tempat harus cocok dengan salah satu nilai jenis utama yang ditentukan agar dapat disertakan dalam respons.

  Sebuah tempat hanya dapat memiliki satu jenis utama dari beberapa jenis Tabel A atau Tabel B yang terkait dengannya. Misalnya, jenis utama mungkin adalah "mexican_restaurant" atau "steak_house".

  Permintaan ditolak dengan error INVALID_REQUEST jika:

  • Lebih dari lima jenis ditentukan.
  • Setiap jenis yang tidak dikenal akan ditentukan.

  Untuk menetapkan parameter jenis utama, panggil setTypesFilter() saat membangun objek FindAutocompletePredictionsRequest.

• Negara

  Hanya sertakan hasil dari daftar negara yang ditentukan, yang ditentukan sebagai daftar yang berisi hingga 15 negara ccTLD ("domain level teratas") nilai yang sama dengan dua karakter. Jika dihilangkan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi wilayah ke Jerman dan Prancis:

  Jika Anda menentukan locationRestriction dan includedRegionCodes, hasilnya berada di area perpotongan dari dua pengaturan.

  Untuk menetapkan parameter negara, panggil setCountries() saat membangun objek FindAutocompletePredictionsRequest.

• 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 setInputOffset() saat membangun objek FindAutocompletePredictionsRequest.

• Bias lokasi atau pembatasan lokasi

  Anda dapat menentukan bias lokasi atau pembatasan lokasi, namun tidak keduanya, untuk mendefinisikan area pencarian. Bayangkan pembatasan lokasi sebagai menentukan wilayah di mana hasilnya harus berada dalam, dan bias lokasi sebagai yang menetapkan region di mana hasilnya harus dekat. Perbedaan utamanya adalah dengan bias lokasi, hasil di luar wilayah yang telah ditentukan mungkin tetap ditampilkan.

  • Bias lokasi

    Menentukan area yang akan ditelusuri. Lokasi ini berfungsi sebagai bias, bukan pembatasan, sehingga hasil di luar area yang ditentukan masih dapat ditampilkan.

    Untuk menetapkan parameter bias lokasi, panggil setLocationBias() saat membangun objek FindAutocompletePredictionsRequest.

  • Pembatasan lokasi

    Menentukan area yang akan ditelusuri. Hasil di luar area yang ditentukan tidak dikembalikan.

    Untuk menetapkan parameter pembatasan lokasi, panggil setLocationRestriction() saat membangun objek FindAutocompletePredictionsRequest.

  Menentukan bias lokasi atau wilayah pembatasan lokasi sebagai {i>Viewport<i} persegi panjang atau sebagai lingkaran.

  • Lingkaran ditentukan dengan titik pusat dan jari-jari dalam meter. Radius harus berada 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 akan menampilkan tidak ada hasil.

  • Persegi panjang adalah area pandang garis lintang dan garis bujur, yang direpresentasikan sebagai dua berlawanan secara diagonal di titik low dan high. Sebuah area pandang dianggap sebagai wilayah tertutup, yang berarti wilayah itu mencakup perbatasannya. Batas lintang harus berkisar antara -90 hingga 90 derajat inklusif, dan batas bujur harus berkisar antara -180 hingga 180 derajat, termasuk:

    Catatan: Jenis bias yang didukung bervariasi bergantung pada versi SDK yang Anda gunakan. CircularBounds hanya tersedia di Autocomplete (Baru).
    • Jika low = high, area pandang terdiri dari titik tunggal tersebut.
    • Jika low.longitude > high.longitude, rentang bujur dibalik (area pandang melintasi garis bujur 180 derajat).
    • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang mencakup semua garis bujur.
    • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.

    Baik low maupun high harus diisi, dan kotak yang ditampilkan wajib diisi. Area pandang kosong akan menyebabkan error.

• Asal

  Titik asal untuk menghitung jarak garis lurus ke tujuan (diakses menggunakan getDistanceMeters()). Jika nilai ini dihilangkan, jarak garis lurus tidak akan dikembalikan. Harus ditetapkan sebagai koordinat lintang dan bujur:

  Untuk menetapkan parameter origin, panggil setOrigin() saat membangun objek FindAutocompletePredictionsRequest.

• Kode wilayah

  Kode wilayah yang digunakan untuk memformat respons, termasuk pemformatan alamat, yang ditentukan sebagai ccTLD ("domain level teratas") nilai yang sama dengan dua karakter. 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 "Inggris Raya dan Irlandia Utara").

  Catatan: Kode wilayah dimaksudkan untuk mewakili wilayah asal permintaan bukan wilayah target untuk kueri tersebut.

  Jika Anda menetapkan kode wilayah yang tidak valid, API akan menampilkan INVALID_ARGUMENT {i>error<i}. Parameter ini dapat memengaruhi hasil berdasarkan hukum yang berlaku.

  Untuk menetapkan parameter kode wilayah, panggil setRegionCode() saat membangun objek FindAutocompletePredictionsRequest.

• 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 untuk tujuan penagihan. Sesi dimulai ketika pengguna mulai mengetik kueri, dan menyimpulkan saat memilih tempat. Setiap sesi dapat memiliki beberapa kueri, diikuti dengan satu pilihan tempat. Setelah sesi memiliki menyimpulkan, token tidak lagi valid; aplikasi Anda harus menghasilkan token baru untuk setiap sesi. Sebaiknya gunakan token sesi untuk semua sesi pelengkapan otomatis (saat Anda menyematkan fragmen, atau meluncurkan pelengkapan otomatis menggunakan intent, API akan menanganinya secara otomatis).

  Pelengkapan Otomatis menggunakan AutocompleteSessionToken untuk mengidentifikasi setiap sesi. Aplikasi Anda harus meneruskan token sesi baru pada memulai setiap sesi baru, lalu meneruskan token yang sama, bersama ID Tempat, di panggilan berikutnya ke fetchPlace() untuk mengambil Place Details untuk tempat yang dipilih oleh pengguna.

  Untuk menetapkan parameter token sesi, panggil setSessionToken() saat membangun objek FindAutocompletePredictionsRequest.

  Untuk informasi selengkapnya, lihat Token sesi.

Contoh Autocomplete (Baru)

Gunakan pembatasan lokasi dan bias lokasi

Autocomplete (Baru) menggunakan pembiasan IP secara default ke mengontrol area pencarian. Dengan pembiasan IP, API menggunakan alamat IP perangkat untuk membuat hasilnya menjadi bias. Anda juga dapat menggunakan location pembatasan atau bias lokasi, tetapi tidak keduanya untuk menentukan area yang akan ditelusuri.

Pembatasan lokasi menentukan area yang akan ditelusuri. Hasil di luar yang ditentukan area tidak 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 yang telah ditentukan area tersebut. 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());
        })
    );

Gunakan jenis utama

Gunakan parameter jenis utama untuk membatasi hasil dari permintaan untuk jenis tertentu seperti yang tercantum dalam Tabel A dan Tabel B. Anda dapat menentukan array yang berisi hingga lima nilai. Jika dihilangkan, semua jenis akan ditampilkan.

Contoh berikut menentukan string kueri "Sepak Bola" dan menggunakan metode parameter jenis untuk membatasi hasil pada pembentukan tipe "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 menghapus parameter jenis utama, hasilnya dapat menyertakan tempat usaha dari jenis yang mungkin tidak Anda inginkan, seperti "athletic_field".

Gunakan origin

Saat Anda menyertakan parameter origin dalam permintaan, yang ditentukan sebagai koordinat lintang dan bujur, API ini menyertakan jarak garis lurus dari tempat asal ke tujuan dalam respons (diakses menggunakan getDistanceMeters()). Contoh ini menyetel tempat 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, maka harus peta Google. Saat Anda menampilkan prediksi dari layanan Autocomplete (Baru) tanpa peta, Anda harus menyertakan logo Google yang ditampilkan sebaris dengan hasil/kolom penelusuran. Sebagai informasi selengkapnya, lihat Menampilkan logo Google dan atribusi.