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 dan substring lengkap dari input, me-resolve nama tempat, alamat, dan plus code. 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 terbatas pada San Francisco, CA. Responsnya 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 ditampilkan kepada pengguna untuk membantu mereka memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (Baru) 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 Autocomplete 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 ini 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 dari 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 sorotan.
  • getPrimaryText(CharacterStyle) menampilkan teks utama yang mendeskripsikan tempat. Ini biasanya adalah nama tempat. Contoh: "Eiffel Tower", dan "123 Pitt Street".
  • getSecondaryText(CharacterStyle) menampilkan teks anak perusahaan dari deskripsi tempat. Hal ini berguna, 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 ID tekstual yang secara unik mengidentifikasi tempat, yang dapat digunakan untuk mengambil objek Place lagi nanti. Untuk informasi selengkapnya tentang ID tempat di Autocomplete, lihat Place Details (Baru). Untuk mengetahui 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 tempat asal yang ditentukan dalam permintaan.

Parameter wajib

  • Kueri

    String teks yang akan ditelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan plus code. Layanan Autocomplete (Baru) menampilkan kandidat berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang dirasakan.

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

Parameter opsional

  • Jenis utama

    Daftar yang berisi 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 dapat disertakan dalam respons.

    Tempat hanya dapat memiliki satu jenis utama dari 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 metode setTypesFilter() saat membuat objek FindAutocompletePredictionsRequest.

  • Negara

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

    Jika Anda menentukan locationRestriction dan includedRegionCodes, hasilnya berada di area perpotongan dari kedua setelan.

    Untuk menetapkan parameter negara, panggil metode setCountries() saat membuat 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 panjang kueri akan ditetapkan secara default.

    Untuk menetapkan parameter offset input, panggil metode setInputOffset() saat mem-build objek FindAutocompletePredictionsRequest.

  • Bias lokasi atau pembatasan lokasi

    Anda dapat menentukan bias lokasi atau pembatasan lokasi, tetapi tidak keduanya, untuk menentukan area penelusuran. Bayangkan pembatasan lokasi sebagai cara menentukan wilayah tempat hasil harus berada, dan bias lokasi dengan menentukan wilayah tempat hasil harus berada dekat. 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 pembatasan, sehingga hasil di luar area yang ditentukan mungkin masih ditampilkan.

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

    • Pembatasan lokasi

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

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

    Tentukan bias lokasi atau wilayah pembatasan lokasi sebagai Area Pandang persegi panjang atau dalam bentuk lingkaran.

    • Lingkaran ditentukan dengan titik pusat dan jari-jari dalam meter. Radius harus antara 0,0 dan 50.000,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 tampilan garis lintang dan garis bujur, yang direpresentasikan sebagai dua titik yang secara diagonal berlawanan low dan high. Area tampilan dianggap sebagai wilayah tertutup, yang berarti area tersebut menyertakan 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 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 akan menyertakan semua bujur.
      • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.

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

  • Origin

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

    Untuk menetapkan parameter asal, panggil metode setOrigin() saat mem-build objek FindAutocompletePredictionsRequest.

  • Kode wilayah

    Kode wilayah yang digunakan untuk memformat respons, termasuk pemformatan alamat, yang ditetapkan 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 "Inggris Raya dan Irlandia Utara").

    Jika Anda menetapkan 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 membuat objek FindAutocompletePredictionsRequest.

  • Token sesi

    Token sesi adalah string buatan pengguna yang melacak panggilan Autocomplete (Baru) 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, diikuti dengan satu pilihan tempat. Setelah sesi selesai, token tidak lagi valid. Aplikasi Anda harus menghasilkan 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 setelah memulai setiap sesi baru, lalu meneruskan token yang sama tersebut, bersama dengan ID Tempat, dalam panggilan berikutnya ke fetchPlace() guna mengambil Place Details untuk tempat yang dipilih oleh pengguna.

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

    Untuk informasi selengkapnya, lihat Token sesi.

Contoh Autocomplete (Baru)

Gunakan pembatasan lokasi dan bias lokasi

Autocomplete (Baru) menggunakan pembiasan IP secara default untuk mengontrol area penelusuran. Dengan pembiasan IP, API menggunakan alamat IP perangkat untuk membiaskan hasil. Secara opsional, Anda dapat 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());
        })
    );

Gunakan jenis utama

Gunakan parameter jenis utama untuk membatasi hasil dari permintaan menjadi 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 parameter jenis utama untuk membatasi hasil ke pendirian 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 menghapus parameter jenis utama, hasilnya dapat mencakup tempat dari jenis yang mungkin tidak Anda inginkan, seperti "athletic_field".

Gunakan origin

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