Pelengkapan Otomatis (Baru)

Pilih platform: Android iOS JavaScript Layanan Web

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.

Catatan: Autocomplete (Baru) tersedia di Places SDK for Android versi 3.5.0 dan yang lebih baru. Untuk mengetahui informasi selengkapnya, lihat Memilih versi SDK. Untuk informasi selengkapnya tentang penggunaan API Kotlin yang ditambahkan dalam versi 4.0.0, lihat Ringkasan Referensi.

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 ini 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());
        })
    );

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

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

Anda dapat menggunakan CancellationToken untuk mencoba membatalkan permintaan ke salah satu class permintaan (misalnya, FetchPlaceRequest). Pembatalan dilakukan berdasarkan upaya terbaik. Setelah permintaan pembatalan dikeluarkan, tidak ada respons yang akan ditampilkan. Mengeluarkan token pembatalan TIDAK menjamin bahwa permintaan tertentu akan dibatalkan, dan Anda mungkin masih ditagih untuk permintaan tersebut meskipun tidak ada respons yang ditampilkan.

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, menggunakan CharacterStyle. Parameter CharacterStyle 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 objek Place 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 objek FindAutocompletePredictionsRequest.

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 objek FindAutocompletePredictionsRequest.

• 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 dan includedRegionCodes, hasilnya akan berada di area persimpangan kedua setelan tersebut.

  Untuk menetapkan parameter negara, panggil metode setCountries() saat mem-build objek FindAutocompletePredictionsRequest.

• 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 objek FindAutocompletePredictionsRequest.

• 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 objek FindAutocompletePredictionsRequest.

  • 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 objek FindAutocompletePredictionsRequest.

  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 dan high 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:

    Catatan: Jenis bias yang didukung bervariasi bergantung pada versi SDK yang Anda gunakan. CircularBounds hanya tersedia di Pelengkapan Otomatis (Baru).
    • 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 dan high.longitude = 180 derajat, area pandang akan menyertakan semua bujur.
    • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur akan kosong.

    low dan high harus diisi, dan kotak yang direpresentasikan tidak boleh kosong. Area pandang kosong akan menghasilkan error.

• 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 objek FindAutocompletePredictionsRequest.

• 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").

  Catatan: Kode wilayah dimaksudkan untuk mewakili wilayah tempat permintaan berasal, bukan wilayah target untuk kueri.

  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 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 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 ke fetchPlace() untuk mengambil Place Details untuk tempat yang dipilih oleh pengguna.

  Untuk menetapkan parameter token sesi, panggil metode setSessionToken() saat mem-build objek FindAutocompletePredictionsRequest.

  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.