Place Autocomplete

Layanan Autocomplete di Places SDK for Android menampilkan tempat prediksi sebagai respons atas kueri penelusuran pengguna. Saat pengguna mengetik, layanan Autocomplete menampilkan saran untuk tempat seperti bisnis, alamat, Plus Codes, dan lokasi menarik lainnya.

Anda bisa menambahkan pelengkapan otomatis ke aplikasi dengan cara berikut:

• Tambahkan widget pelengkapan otomatis untuk menyimpan pengembangan aplikasi dan memastikan pengalaman pengguna yang konsisten.
• Mendapatkan prediksi tempat secara terprogram untuk membuat pengalaman pengguna yang disesuaikan.

Menambahkan widget pelengkapan otomatis

Widget pelengkapan otomatis adalah dialog penelusuran dengan pelengkapan otomatis bawaan fungsionalitasnya. Saat pengguna memasukkan istilah penelusuran, widget akan menampilkan daftar prediksi tempat untuk dipilih. Saat pengguna membuat pilihan, Place akan ditampilkan, yang kemudian dapat digunakan aplikasi untuk mendapatkan detail tentang tempat yang dipilih.

Ada dua opsi untuk menambahkan widget pelengkapan otomatis ke aplikasi Anda:

• Opsi 1: Menyematkan AutocompleteSupportFragment.
• Opsi 2: Gunakan intent untuk meluncurkan aktivitas pelengkapan otomatis.

Opsi 1: Menyematkan AutocompleteSupportFragment

Untuk menambahkan AutocompleteSupportFragment ke aplikasi Anda, lakukan langkah-langkah berikut:

1. Tambahkan fragmen ke tata letak XML aktivitas Anda.
2. Tambahkan pemroses ke aktivitas atau fragmen Anda.

Menambahkan AutocompleteSupportFragment ke aktivitas

Untuk menambahkan AutocompleteSupportFragment ke aktivitas, tambahkan fragmen baru ke tata letak XML. Contoh:

<fragment android:id="@+id/autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.libraries.places.widget.AutocompleteSupportFragment"
  />

• Secara default, fragmen tidak memiliki border atau latar belakang. Untuk memberikan tampilan visual yang konsisten, tempatkan fragmen di dalam tata letak lain seperti CardView.
• Jika Anda menggunakan fragmen Autocomplete dan perlu mengganti onActivityResult, Anda harus memanggil super.onActivityResult. Jika tidak, fragmen tidak akan berfungsi dengan baik.

Menambahkan PlaceSelectionListener ke aktivitas

PlaceSelectionListener menangani pengembalian tempat sebagai respons terhadap permintaan pengguna pilihan. Kode berikut menunjukkan pembuatan referensi ke fragmen dan menambahkan pemroses ke AutocompleteSupportFragment:

    // Initialize the AutocompleteSupportFragment.
    val autocompleteFragment =
        supportFragmentManager.findFragmentById(R.id.autocomplete_fragment)
                as AutocompleteSupportFragment

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(listOf(Place.Field.ID, Place.Field.NAME))

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(object : PlaceSelectionListener {
        override fun onPlaceSelected(place: Place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: ${place.name}, ${place.id}")
        }

        override fun onError(status: Status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: $status")
        }
    })

      

    // Initialize the AutocompleteSupportFragment.
    AutocompleteSupportFragment autocompleteFragment = (AutocompleteSupportFragment)
            getSupportFragmentManager().findFragmentById(R.id.autocomplete_fragment);

    // Specify the types of place data to return.
    autocompleteFragment.setPlaceFields(Arrays.asList(Place.Field.ID, Place.Field.NAME));

    // Set up a PlaceSelectionListener to handle the response.
    autocompleteFragment.setOnPlaceSelectedListener(new PlaceSelectionListener() {
        @Override
        public void onPlaceSelected(@NonNull Place place) {
            // TODO: Get info about the selected place.
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        }


        @Override
        public void onError(@NonNull Status status) {
            // TODO: Handle the error.
            Log.i(TAG, "An error occurred: " + status);
        }
    });

      

Opsi 2: Gunakan intent untuk meluncurkan aktivitas pelengkapan otomatis

Jika Anda ingin aplikasi menggunakan alur navigasi yang berbeda (misalnya, untuk memicu pengalaman pelengkapan otomatis dari ikon, bukan kolom penelusuran), aplikasi Anda bisa meluncurkan pelengkapan otomatis dengan menggunakan intent.

Untuk meluncurkan widget pelengkapan otomatis dengan menggunakan maksud, ikuti langkah-langkah ini:

1. Gunakan Autocomplete.IntentBuilder untuk membuat intent, dengan meneruskan mode Autocomplete yang diinginkan.
2. Menentukan peluncur hasil aktivitas registerForActivityResult yang dapat digunakan untuk meluncurkan intent dan menangani tempat yang dipilih pengguna prediksi dalam hasil.

Membuat intent pelengkapan otomatis

Contoh di bawah ini menggunakan Autocomplete.IntentBuilder untuk membuat intent guna meluncurkan widget pelengkapan otomatis sebagai intent:

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    val fields = listOf(Place.Field.ID, Place.Field.NAME)

    // Start the autocomplete intent.
    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .build(this)
    startAutocomplete.launch(intent)

      

    // Set the fields to specify which types of place data to
    // return after the user has made a selection.
    List<Place.Field> fields = Arrays.asList(Place.Field.ID, Place.Field.NAME);

    // Start the autocomplete intent.
    Intent intent = new Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
            .build(this);
    startAutocomplete.launch(intent);

      

Saat menggunakan intent untuk meluncurkan widget pelengkapan otomatis, Anda bisa memilih dari mode tampilan overlay atau layar penuh. Screenshot berikut menunjukkan masing-masing mode tampilan masing-masing:

Mendaftarkan callback untuk hasil intent

Untuk menerima notifikasi saat pengguna telah memilih tempat, tentukan Peluncur registerForActivityResult(), yang meluncurkan aktivitas dan juga menangani seperti yang ditunjukkan dalam contoh berikut. Jika pengguna memilih sebuah prediksi, akan dikirim dalam intent yang terdapat dalam objek hasil. Karena tujuannya dibuat oleh Autocomplete.IntentBuilder, metode ini Autocomplete.getPlaceFromIntent() dapat mengekstrak objek Tempat darinya.

private val startAutocomplete =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        if (result.resultCode == Activity.RESULT_OK) {
            val intent = result.data
            if (intent != null) {
                val place = Autocomplete.getPlaceFromIntent(intent)
                Log.i(
                    TAG, "Place: ${place.name}, ${place.id}"
                )
            }
        } else if (result.resultCode == Activity.RESULT_CANCELED) {
            // The user canceled the operation.
            Log.i(TAG, "User canceled autocomplete")
        }
    }

      

private final ActivityResultLauncher<Intent> startAutocomplete = registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        result -> {
            if (result.getResultCode() == Activity.RESULT_OK) {
                Intent intent = result.getData();
                if (intent != null) {
                    Place place = Autocomplete.getPlaceFromIntent(intent);
                    Log.i(TAG, "Place: ${place.getName()}, ${place.getId()}");
                }
            } else if (result.getResultCode() == Activity.RESULT_CANCELED) {
                // The user canceled the operation.
                Log.i(TAG, "User canceled autocomplete");
            }
        });

      

Mendapatkan prediksi tempat secara terprogram

Anda dapat membuat UI penelusuran kustom sebagai alternatif UI yang disediakan oleh widget pelengkapan otomatis. Untuk melakukannya, aplikasi Anda harus mendapatkan prediksi tempat secara terprogram. Aplikasi Anda bisa mendapatkan daftar prediksi nama tempat dan/atau dari API pelengkapan otomatis dengan memanggil PlacesClient.findAutocompletePredictions(), meneruskan FindAutocompletePredictionsRequest dengan parameter berikut:

• Wajib: String query berisi teks yang diketik oleh pengguna.
• Direkomendasikan: A AutocompleteSessionToken, yang mengelompokkan fase kueri dan pemilihan dari pencarian pengguna ke dalam kelompok untuk tujuan penagihan. Sesi dimulai saat pengguna mulai mengetik kueri, dan menyimpulkan saat mereka memilih tempat.
• Direkomendasikan: RectangularBounds , yang menetapkan batas garis lintang dan garis bujur untuk memaksa hasil agar region yang ditentukan.
• Opsional: Satu atau beberapa negara dengan dua huruf kode (ISO 3166-1 Alfa-2), menunjukkan satu atau beberapa negara tujuan hasil dibatasi.

• Opsional: A TypeFilter, yang bisa Anda gunakan untuk membatasi hasil ke tipe tempat yang ditentukan. Tujuan jenis tempat berikut ini didukung:

  • TypeFilter.GEOCODE – Hanya menampilkan hasil geocoding, bukan bisnis. Gunakan permintaan ini untuk memperjelas hasil ketika atribut mungkin tidak pasti.
  • TypeFilter.ADDRESS – Hanya menampilkan hasil pelengkapan otomatis dengan alamat yang akurat. Gunakan jenis ini bila Anda mengetahui pengguna mencari alamat yang telah ditentukan dengan lengkap.
  • TypeFilter.ESTABLISHMENT – Hanya menampilkan tempat yang bisnis.

  • TypeFilter.REGIONS – Hanya menampilkan tempat yang cocok dengan salah satu jenis berikut:

  • LOCALITY

  • SUBLOCALITY

  • POSTAL_CODE

  • COUNTRY

  • ADMINISTRATIVE_AREA_LEVEL_1

  • ADMINISTRATIVE_AREA_LEVEL_2

  • TypeFilter.CITIES – Menampilkan hanya hasil yang cocok dengan LOCALITY atau ADMINISTRATIVE_AREA_LEVEL_3.

• Opsional: LatLng yang menentukan lokasi asal untuk permintaan. Saat Anda menelepon setOrigin(), layanan menampilkan jarak dalam meter (distanceMeters) dari origin, untuk setiap prediksi pelengkapan otomatis dalam respons.

Untuk informasi tentang jenis tempat, lihat panduan tempat jenis data.

Contoh di bawah ini menunjukkan panggilan lengkap untuk PlacesClient.findAutocompletePredictions()

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    val token = AutocompleteSessionToken.newInstance()

    // Create a RectangularBounds object.
    val bounds = RectangularBounds.newInstance(
        LatLng(-33.880490, 151.184363),
        LatLng(-33.858754, 151.229596)
    )
    // Use the builder to create a FindAutocompletePredictionsRequest.
    val request =
        FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(listOf(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build()
    placesClient.findAutocompletePredictions(request)
        .addOnSuccessListener { response: FindAutocompletePredictionsResponse ->
            for (prediction in response.autocompletePredictions) {
                Log.i(TAG, prediction.placeId)
                Log.i(TAG, prediction.getPrimaryText(null).toString())
            }
        }.addOnFailureListener { exception: Exception? ->
            if (exception is ApiException) {
                Log.e(TAG, "Place not found: ${exception.statusCode}")
            }
        }

      

    // Create a new token for the autocomplete session. Pass this to FindAutocompletePredictionsRequest,
    // and once again when the user makes a selection (for example when calling fetchPlace()).
    AutocompleteSessionToken token = AutocompleteSessionToken.newInstance();

    // Create a RectangularBounds object.
    RectangularBounds bounds = RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596));
    // Use the builder to create a FindAutocompletePredictionsRequest.
    FindAutocompletePredictionsRequest request = FindAutocompletePredictionsRequest.builder()
            // Call either setLocationBias() OR setLocationRestriction().
            .setLocationBias(bounds)
            //.setLocationRestriction(bounds)
            .setOrigin(new LatLng(-33.8749937, 151.2041382))
            .setCountries("AU", "NZ")
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .setSessionToken(token)
            .setQuery(query)
            .build();

    placesClient.findAutocompletePredictions(request).addOnSuccessListener((response) -> {
        for (AutocompletePrediction prediction : response.getAutocompletePredictions()) {
            Log.i(TAG, prediction.getPlaceId());
            Log.i(TAG, prediction.getPrimaryText(null).toString());
        }
    }).addOnFailureListener((exception) -> {
        if (exception instanceof ApiException) {
            ApiException apiException = (ApiException) exception;
            Log.e(TAG, "Place not found: " + apiException.getStatusCode());
        }
    });

      

API menampilkan FindAutocompletePredictionsResponse dalam Task. FindAutocompletePredictionsResponse berisi daftar 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 tidak membutuhkan penyorotan.
• 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 Places SDK for Android, lihat bagian Place SDK for Android Detail. Untuk umum informasi tentang ID tempat, lihat ID Tempat ringkasan.
• getPlaceTypes() 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.

Token sesi

Token sesi mengelompokkan fase kueri dan pemilihan dari pelengkapan otomatis pengguna menelusuri ke sesi terpisah 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).

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

Pelajari sesi lebih lanjut token.

Membatasi hasil pelengkapan otomatis

Anda dapat membatasi hasil pelengkapan otomatis ke wilayah geografis tertentu, dan/atau filter hasil menurut satu atau beberapa jenis tempat, atau hingga lima negara. Anda bisa menerapkan batasan ini pada aktivitas pelengkapan otomatis, AutocompleteSupportFragment, dan API pelengkapan otomatis terprogram.

Untuk membatasi hasil, lakukan hal berikut:

• Untuk memilih hasil dalam wilayah yang ditentukan, panggil setLocationBias() (beberapa hasil dari luar wilayah yang ditentukan mungkin masih ditampilkan).
• Untuk hanya menampilkan hasil dalam wilayah yang ditentukan, panggil setLocationRestriction() (hanya hasil dalam wilayah yang ditentukan yang akan dikembalikan).
• Untuk hanya mengembalikan hasil yang sesuai dengan tipe tempat tertentu, panggil setTypesFilter() (misalnya, menentukan TypeFilter.ADDRESS akan menampilkan hanya hasil dengan alamat yang akurat).
• Untuk hanya menampilkan hasil dalam wilayah maksimal lima negara yang ditentukan, panggil setCountries(). Negara harus diteruskan berupa dua karakter, ISO 3166-1 Negara yang kompatibel dengan Alfa-2 dari kode Anda.

Membiaskan hasil ke wilayah tertentu

Untuk membiaskan hasil pelengkapan otomatis ke wilayah geografis tertentu, panggil setLocationBias(), meneruskan RectangularBounds. Contoh kode berikut menunjukkan pemanggilan setLocationBias() pada fragmen untuk mencondongkan saran pelengkapan otomatisnya ke region Sydney, Australia.

    autocompleteFragment.setLocationBias(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

    autocompleteFragment.setLocationBias(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Membatasi hasil ke wilayah tertentu

Untuk membatasi hasil pelengkapan otomatis ke wilayah geografis tertentu, panggil setLocationRestriction(), meneruskan RectangularBounds. Contoh kode berikut menunjukkan cara memanggil setLocationRestriction() pada instance fragmen untuk mencondongkan saran pelengkapan otomatisnya ke region Sydney, Australia.

    autocompleteFragment.setLocationRestriction(
        RectangularBounds.newInstance(
            LatLng(-33.880490, 151.184363),
            LatLng(-33.858754, 151.229596)
        )
    )

      

    autocompleteFragment.setLocationRestriction(RectangularBounds.newInstance(
            new LatLng(-33.880490, 151.184363),
            new LatLng(-33.858754, 151.229596)));

      

Catatan: Pembatasan ini hanya berlaku untuk seluruh rute, hasil sintetis yang terletak di luar batas persegi panjang dapat ditampilkan berdasarkan rute yang tumpang tindih dengan pembatasan lokasi.

Filter hasil menurut jenis tempat atau koleksi jenis

Anda dapat membatasi hasil dari permintaan pelengkapan otomatis sehingga hasil hanya menampilkan jenis tempat tertentu. Menentukan filter menggunakan jenis tempat atau koleksi jenis tercantum dalam Tabel 1, 2, dan 3 pada Jenis Tempat. Jika tidak ada ditentukan, semua jenis akan dikembalikan.

Untuk memfilter hasil pelengkapan otomatis, panggil setTypesFilter() untuk menyetel filter.

Untuk menentukan jenis atau filter koleksi jenis:

• Panggil setTypesFilter() dan tentukan hingga lima nilai type dari Tabel 1 dan Tabel 2 yang ditampilkan di Jenis Tempat. Nilai jenisnya adalah yang ditentukan oleh konstanta di PlaceTypes.

• Panggil setTypesFilter() dan tentukan koleksi jenis dari Tabel 3 yang ditampilkan di Jenis Tempat. Nilai koleksi ditentukan oleh atribut konstanta di PlaceTypes.

  Hanya satu jenis dari Tabel 3 yang diizinkan dalam permintaan. Jika Anda menentukan nilai dari Tabel 3, Anda tidak dapat menentukan nilai dari Tabel 1 atau Tabel 2. Jika yang Anda lakukan, maka terjadi kesalahan.

Contoh kode berikut memanggil setTypesFilter() di AutocompleteSupportFragment dan menentukan beberapa nilai jenis.

    autocompleteFragment.setTypesFilter(listOf("landmark", "restaurant", "store"))

      

    autocompleteFragment.setTypesFilter(Arrays.asList("landmark", "restaurant", "store"));

      

Contoh kode berikut menunjukkan cara memanggil setTypesFilter() pada AutocompleteSupportFragment untuk menetapkan filter yang hanya menampilkan hasil dengan alamat yang akurat dengan menentukan suatu jenis.

    autocompleteFragment.setTypesFilter(listOf(PlaceTypes.ADDRESS))

      

    autocompleteFragment.setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS, PlaceTypes.ESTABLISHMENT));

      

Contoh kode berikut menunjukkan cara memanggil setTypesFilter() pada IntentBuilder untuk menyetel filter yang hanya menampilkan hasil dengan alamat yang akurat berdasarkan menentukan jenis koleksi.

    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(PlaceTypes.ADDRESS))
        .build(this)

      

    Intent intent = new Autocomplete.IntentBuilder(
            AutocompleteActivityMode.FULLSCREEN, fields)
            .setTypesFilter(Arrays.asList(PlaceTypes.ADDRESS))
            .build(this);

      

Filter hasil menurut negara

Untuk memfilter hasil pelengkapan otomatis ke maksimal lima negara, panggil setCountries() untuk menetapkan kode negara. Kemudian, teruskan filter ke fragmen atau maksud. Negara harus diteruskan sebagai dua karakter, negara yang kompatibel dengan ISO 3166-1 Alpha-2 dari kode Anda.

Contoh kode berikut menunjukkan cara memanggil setCountries() pada AutocompleteSupportFragment, untuk menyetel filter yang hanya menampilkan hasil dalam negara tertentu.

    autocompleteFragment.setCountries("AU", "NZ")

      

    autocompleteFragment.setCountries("AU", "NZ");

      

Batas penggunaan

Penggunaan Places API, termasuk Places SDK for Android, adalah tidak lagi dibatasi pada jumlah maksimum permintaan per hari (QPD). Namun, batas penggunaan berikut tetap berlaku:

• Batas kapasitas adalah 6.000 QPM (permintaan per menit). Penting dihitung sebagai jumlah permintaan sisi klien dan sisi server untuk semua aplikasi menggunakan kredensial dari project yang sama.

Menampilkan atribusi dalam aplikasi Anda

• Jika aplikasi Anda menggunakan layanan pelengkapan otomatis secara terprogram, UI harus menampilkan gambar 'Didukung oleh Google' atribusi, atau muncul dalam Peta merek Google.
• Jika aplikasi Anda menggunakan widget pelengkapan otomatis, Anda tidak perlu melakukan tindakan tambahan (atribusi yang diperlukan ditampilkan secara default).
• Jika Anda mengambil dan menampilkan tambahan informasi tempat setelah mendapatkan tempat menurut ID, Anda harus menampilkan atribusi pihak ketiga juga.

Untuk detail selengkapnya, lihat dokumentasi di atribusi.

Pengoptimalan Place Autocomplete

Bagian ini menjelaskan praktik terbaik untuk membantu Anda memaksimalkan layanan Place Autocomplete.

Berikut ini beberapa pedoman umum:

• Cara tercepat untuk membuat antarmuka pengguna yang berfungsi baik adalah dengan menggunakan widget Autocomplete Maps JavaScript API, widget Autocomplete Places SDK for Android, atau Kontrol UI Autocomplete Places SDK for iOS
• Kembangkan pemahaman tentang kolom data Place Autocomplete yang penting sejak awal.
• Kolom pembiasan lokasi dan pembatasan lokasi bersifat opsional, tetapi dapat memberikan dampak signifikan terhadap performa pelengkapan otomatis.
• Gunakan penanganan error untuk memastikan aplikasi Anda terdegrasi secara halus jika API menampilkan error.
• Pastikan aplikasi Anda menanganinya jika tidak ada pilihan dan menawarkan cara kepada pengguna untuk melanjutkan.

Praktik terbaik pengoptimalan biaya

Pengoptimalan biaya dasar

Untuk mengoptimalkan biaya penggunaan layanan Place Autocomplete, gunakan mask kolom dalam widget Place Details dan Place Autocomplete agar hanya menampilkan kolom data tempat yang Anda butuhkan.

Pengoptimalan biaya lanjutan

Pertimbangkan implementasi Place Autocomplete yang terprogram untuk mengakses Harga Per Permintaan dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details. Harga Per Permintaan yang dipasangkan dengan Geocoding API lebih hemat biaya daripada harga Per Sesi (berbasis sesi) jika kondisi berikut terpenuhi:

• Jika Anda hanya memerlukan lintang/bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini dengan biaya yang lebih murah daripada panggilan Place Details.
• Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete atau kurang, harga Per Permintaan mungkin lebih hemat biaya daripada harga Per Sesi.

Apakah aplikasi Anda memerlukan informasi selain alamat dan lintang/bujur dari prediksi yang dipilih?

Praktik terbaik performa

Panduan berikut menjelaskan cara mengoptimalkan performa Place Autocomplete:

• Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Place Autocomplete Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
• Jika Place Autocomplete disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
• Jika pengguna tidak memilih salah satu prediksi Autocomplete, umumnya karena tidak satu pun prediksi tersebut yang merupakan alamat hasil yang diinginkan, Anda dapat menggunakan kembali input pengguna yang asli untuk mendapatkan hasil yang lebih relevan:
  • Jika Anda mengharapkan pengguna hanya memasukkan informasi alamat, gunakan kembali input pengguna yang asli dalam panggilan ke Geocoding API.
  • Jika Anda memperkirakan pengguna akan memasukkan kueri untuk tempat tertentu berdasarkan nama atau alamat, gunakan permintaan Find Place. Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
  Skenario lain saat Anda sebaiknya beralih kembali ke Geocoding API mencakup:
  • Pengguna memasukkan alamat subpremis di negara yang tidak memiliki dukungan lengkap untuk Place Autocomplete, misalnya Republik Ceko, Estonia, dan Lituania. Misalnya, alamat Ceko "Stroupežnického 3191/17, Praha" akan menghasilkan prediksi parsial di Place Autocomplete.
  • Pengguna memasukkan alamat dengan awalan segmen jalan seperti "23-30 29th St, Queens" di New York City atau "47-380 Kamehameha Hwy, Kaneohe" di pulau Kauai di Hawai'i.

Pemecahan masalah

Meskipun berbagai macam error bisa terjadi, sebagian besar error yang terjadi di aplikasi Anda kemungkinan dialami pengguna biasanya disebabkan oleh error konfigurasi (misalnya, kunci API yang digunakan salah, atau kunci API tidak dikonfigurasi dengan benar), atau error (aplikasi Anda telah melebihi kuotanya). Lihat Penggunaan Batas untuk mengetahui info selengkapnya informasi tentang kuota.

Error yang terjadi dalam penggunaan kontrol pelengkapan otomatis ditampilkan di bagian Callback onActivityResult(). Panggil Autocomplete.getStatus() untuk mendapatkan status pesan untuk hasilnya.