Place Autocomplete

Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.
Pilih platform: Android iOS JavaScript Layanan Web

Layanan pelengkapan otomatis di Places SDK for Android menampilkan prediksi tempat sebagai respons terhadap kueri penelusuran pengguna. Saat pengguna mengetik, layanan pelengkapan otomatis menampilkan saran untuk tempat seperti bisnis, alamat, plus Codes, dan lokasi menarik.

Anda bisa menambahkan pelengkapan otomatis ke aplikasi dengan cara berikut:

Menambahkan widget pelengkapan otomatis

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

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

Opsi 1: Sematkan 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 elemen tata letak lain seperti CardView.
  • Jika menggunakan fragmen Autocomplete, dan perlu mengganti onActivityResult, Anda harus memanggil super.onActivityResult, jika tidak, fragmen tidak akan berfungsi dengan benar.

Menambahkan PlaceSelectionListener ke aktivitas

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

Java


    // 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);
        }
    });

      

Kotlin


    // 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")
        }
    })

      

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 dari kolom penelusuran), aplikasi Anda dapat meluncurkan pelengkapan otomatis 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. Intent harus memanggil startActivityForResult, yang meneruskan kode permintaan yang mengidentifikasi intent.
  2. Ganti callback onActivityResult untuk menerima tempat yang dipilih.

Membuat intent pelengkapan otomatis

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

Java


    private static int AUTOCOMPLETE_REQUEST_CODE = 1;

    // 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);
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE);

      

Kotlin


    private val AUTOCOMPLETE_REQUEST_CODE = 1

    // 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)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Saat menggunakan intent untuk meluncurkan widget pelengkapan otomatis, Anda dapat memilih dari mode tampilan overlay atau layar penuh. Screenshot berikut menampilkan setiap mode tampilan:

Saat ditampilkan dalam mode overlay, widget pelengkapan otomatis akan muncul di atas UI panggilan.
Gambar 1: Widget pelengkapan otomatis dalam mode OVERLAY
Jika ditampilkan dalam mode layar penuh, widget pelengkapan otomatis akan mengisi seluruh layar.
Gambar 2: Widget pelengkapan otomatis dalam mode FULLSCREEN

Mengganti callback onActivityResult

Untuk menerima notifikasi saat pengguna telah memilih tempat, aplikasi Anda harus menggantikan onActivityResult() aktivitas, yang memeriksa kode permintaan yang Anda teruskan untuk intent, seperti yang ditunjukkan pada contoh berikut.

Java


@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = Autocomplete.getPlaceFromIntent(data);
            Log.i(TAG, "Place: " + place.getName() + ", " + place.getId());
        } else if (resultCode == AutocompleteActivity.RESULT_ERROR) {
            // TODO: Handle the error.
            Status status = Autocomplete.getStatusFromIntent(data);
            Log.i(TAG, status.getStatusMessage());
        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
        return;
    }
    super.onActivityResult(requestCode, resultCode, data);
}

      

Kotlin


override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    if (requestCode == AUTOCOMPLETE_REQUEST_CODE) {
        when (resultCode) {
            Activity.RESULT_OK -> {
                data?.let {
                    val place = Autocomplete.getPlaceFromIntent(data)
                    Log.i(TAG, "Place: ${place.name}, ${place.id}")
                }
            }
            AutocompleteActivity.RESULT_ERROR -> {
                // TODO: Handle the error.
                data?.let {
                    val status = Autocomplete.getStatusFromIntent(data)
                    Log.i(TAG, status.statusMessage ?: "")
                }
            }
            Activity.RESULT_CANCELED -> {
                // The user canceled the operation.
            }
        }
        return
    }
    super.onActivityResult(requestCode, resultCode, data)
}

      

Mendapatkan prediksi tempat secara terprogram

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

  • Wajib: String query yang berisi teks yang diketik oleh pengguna.
  • Direkomendasikan: AutocompleteSessionToken, yang mengelompokkan fase kueri dan pemilihan penelusuran pengguna ke dalam sesi terpisah untuk tujuan penagihan. Sesi dimulai saat pengguna mulai mengetik kueri, dan berakhir saat mereka memilih tempat.
  • Direkomendasikan: Objek RectangularBounds, yang menentukan batas lintang dan bujur untuk membatasi hasil ke wilayah yang ditentukan.
  • Opsional: Satu atau beberapa kode negara dua huruf (ISO 3166-1 Alpha-2), yang menunjukkan satu atau beberapa negara tempat hasil seharusnya dibatasi.
  • Opsional: TypeFilter, yang dapat Anda gunakan untuk membatasi hasil pada jenis tempat yang ditentukan. Jenis tempat berikut ini didukung:

    • TypeFilter.GEOCODE – Hanya menampilkan hasil geocoding, bukan bisnis. Gunakan permintaan ini untuk membedakan hasil jika lokasi yang ditentukan mungkin tidak dapat ditentukan.
    • TypeFilter.ADDRESS – Hanya menampilkan hasil pelengkapan otomatis dengan alamat yang akurat. Gunakan jenis ini jika Anda mengetahui bahwa pengguna mencari alamat yang ditentukan secara lengkap.
    • TypeFilter.ESTABLISHMENT – Hanya menampilkan tempat yang adalah 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 – Hanya menampilkan hasil yang cocok dengan LOCALITY atau ADMINISTRATIVE_AREA_LEVEL_3.

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

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

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

Java


    // 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(TypeFilter.ADDRESS.toString()))
        .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());
        }
    });

      

Kotlin


    // 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(TypeFilter.ADDRESS.toString()))
            .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)
            }
        }

      

API menampilkan FindAutocompletePredictionsResponse dalam Task. FindAutocompletePredictionsResponse berisi daftar objek AutocompletePrediction yang mewakili tempat yang diprediksi. Daftar tersebut 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 teks utama dan teks 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 penandaan.
  • 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 untuk deskripsi tempat. Hal ini berguna, misalnya, sebagai baris kedua saat menampilkan prediksi pelengkapan otomatis. Contoh: "Away 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 Anda gunakan untuk mengambil objek Place lagi nanti. Untuk informasi selengkapnya tentang ID tempat di Places SDK for Android, lihat Place Details. Untuk informasi umum tentang ID tempat, lihat ringkasan ID Tempat.
  • getPlaceTypes() 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.

Token sesi

Token sesi 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 mereka memilih tempat. Setiap sesi dapat memiliki beberapa kueri, 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 yang terprogram (saat Anda menyematkan fragmen, atau meluncurkan pelengkapan otomatis menggunakan intent, API akan menangani hal ini secara otomatis).

Places SDK for Android menggunakan AutocompleteSessionToken untuk mengidentifikasi setiap sesi. Aplikasi Anda harus meneruskan token sesi baru saat memulai setiap sesi baru, lalu meneruskan token yang sama tersebut, beserta ID Tempat, dalam panggilan berikutnya ke fetchPlace() untuk mengambil Place Details untuk tempat yang dipilih oleh pengguna.

Pelajari token sesi lebih lanjut.

Membatasi hasil pelengkapan otomatis

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

Untuk membatasi hasil, lakukan hal berikut:

  • Untuk lebih memilih hasil dalam region yang ditentukan, panggil setLocationBias() (beberapa hasil dari luar region yang ditentukan mungkin masih ditampilkan).
  • Untuk hanya menampilkan hasil dalam region yang ditentukan, panggil setLocationRestriction() (hanya hasil dalam region yang ditentukan yang akan ditampilkan).
  • Untuk hanya menampilkan hasil yang sesuai dengan jenis tempat tertentu, panggil setTypesFilter() (misalnya, menentukan TypeFilter.ADDRESS hanya akan menampilkan hasil dengan alamat yang akurat).
  • Untuk hanya menampilkan hasil dalam maksimal lima negara yang ditentukan, panggil setCountries(). Negara harus diteruskan sebagai kode negara yang kompatibel dengan ISO 3166-1 Alpha-2.

Bias hasil ke region tertentu

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

Java


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

      

Kotlin


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

      

Batasi hasil pada wilayah tertentu

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

Java


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

      

Kotlin


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

      

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

Memfilter hasil menurut jenis tempat atau kumpulan jenis

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

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

Untuk menentukan jenis atau filter koleksi jenis:

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

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

    Hanya satu jenis dari Tabel 3 yang diizinkan dalam permintaan. Jika menentukan nilai dari Tabel 3, Anda tidak dapat menentukan nilai dari Tabel 1 atau Tabel 2. Jika Anda melakukannya, error akan terjadi.

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

Java


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

      

Kotlin


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

      

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

Java


    autocompleteFragment.setTypesFilter(Arrays.asList(TypeFilter.ADDRESS.toString()));

      

Kotlin


    autocompleteFragment.setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))

      

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

Java


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

      

Kotlin


    val intent = Autocomplete.IntentBuilder(AutocompleteActivityMode.FULLSCREEN, fields)
        .setTypesFilter(listOf(TypeFilter.ADDRESS.toString()))
        .build(this)
    startActivityForResult(intent, AUTOCOMPLETE_REQUEST_CODE)

      

Memfilter 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 kode negara yang kompatibel dengan ISO 3166-1 Alpha-2.

Contoh kode berikut menunjukkan pemanggilan setCountries() pada AutocompleteSupportFragment, untuk menetapkan filter yang hanya menampilkan hasil dalam negara yang ditentukan.

Java


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

      

Kotlin


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

      

Batas penggunaan

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

  • Batas kapasitas adalah 100 permintaan per detik (QPS). Jumlah ini dihitung sebagai jumlah permintaan sisi klien dan sisi server untuk semua aplikasi yang menggunakan kredensial project yang sama.

Menampilkan atribusi dalam aplikasi Anda

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

Untuk mengetahui detail selengkapnya, baca dokumentasi tentang atribusi.

Pengoptimalan Place Autocomplete

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

Berikut ini beberapa pedoman umum:

  • Cara tercepat untuk mengembangkan 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 bias 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 mengembalikan kolom data tempat yang Anda butuhkan.

Pengoptimalan biaya lanjutan

Pertimbangkan implementasi Place Autocomplete yang terprogram untuk mengakses Harga Per Request 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 kedua kondisi berikut terpenuhi:

  • Jika Anda hanya memerlukan lintang/bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini lebih murah daripada panggilan Place Details.
  • Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete atau lebih sedikit, harga Per Permintaan mungkin lebih hemat biaya daripada harga Per Sesi.
Untuk mendapatkan bantuan dalam memilih penerapan Place Autocomplete yang sesuai dengan kebutuhan Anda, pilih tab yang sesuai dengan jawaban Anda untuk pertanyaan berikut.

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

Ya, memerlukan informasi lebih detail

Gunakan Place Autocomplete berbasis sesi dengan Place Details.
Karena aplikasi Anda memerlukan Place Details seperti nama tempat, status bisnis, atau jam buka, penerapan Place Autocomplete harus menggunakan token sesi (secara terprogram atau diintegrasikan ke widget JavaScript, Android, atau iOS) dengan total biaya sebesar $0,017 per sesi ditambah SKU Data Places yang relevan, bergantung pada kolom data tempat yang Anda minta.1

Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget JavaScript, Android, atau iOS. Ini mencakup permintaan Place Autocomplete dan permintaan Place Details pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields untuk memastikan Anda hanya meminta kolom data tempat yang Anda butuhkan.

Penerapan terprogram
Gunakan token sesi dengan permintaan Place Autocomplete Anda. Saat meminta Place Details tentang prediksi yang dipilih, sertakan parameter berikut:

  1. ID tempat dari respons Place Autocomplete
  2. Token sesi yang digunakan dalam permintaan Place Autocomplete
  3. Parameter fields yang menentukan kolom data tempat yang Anda perlukan

Tidak, hanya memerlukan alamat dan lokasi

Geocoding API dapat menjadi opsi yang lebih hemat biaya daripada Place Details untuk aplikasi Anda, bergantung pada performa penggunaan Place Autocomplete. Efisiensi Autocomplete setiap aplikasi bervariasi bergantung pada apa yang dimasukkan oleh pengguna, tempat aplikasi digunakan, dan apakah praktik terbaik pengoptimalan performa telah diterapkan.

Untuk menjawab pertanyaan berikut, analisis rata-rata jumlah karakter yang diketik pengguna sebelum memilih prediksi Place Autocomplete di aplikasi Anda.

Apakah pengguna Anda rata-rata memilih prediksi Place Autocomplete dalam empat permintaan atau kurang?

Ya

Terapkan Place Autocomplete secara terprogram tanpa token sesi dan panggil Geocoding API di prediksi tempat yang dipilih.
Geocoding API memberikan alamat dan koordinat lintang/bujur dengan biaya sebesar $0,005 per permintaan. Membuat empat permintaan Place Autocomplete - Per Request dikenai biaya $0,01132 sehingga total biaya empat permintaan ditambah panggilan Geocoding API tentang prediksi tempat yang dipilih adalah $0,01632, yang lebih rendah daripada harga Autocomplete Per Sesi, yaitu $0,017 per sesi.1

Pertimbangkan untuk menerapkan praktik terbaik performa untuk membantu pengguna mendapatkan prediksi yang mereka cari dalam karakter yang lebih sedikit.

Tidak

Gunakan Place Autocomplete berbasis sesi dengan Place Details.
Karena jumlah rata-rata permintaan yang Anda perkirakan akan dibuat sebelum pengguna memilih prediksi Place Autocomplete melebihi biaya harga Per Sesi, penerapan Place Autocomplete harus menggunakan token sesi untuk permintaan Place Autocomplete dan permintaan Place Details yang terkait dengan total biaya sebesar $0,017 per sesi.1

Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget JavaScript, Android, atau iOS. Ini mencakup permintaan Place Autocomplete dan permintaan Place Details pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields untuk memastikan Anda hanya meminta kolom Basic Data.

Penerapan terprogram
Gunakan token sesi dengan permintaan Place Autocomplete Anda. Saat meminta Place Details tentang prediksi yang dipilih, sertakan parameter berikut:

  1. ID tempat dari respons Place Autocomplete
  2. Token sesi yang digunakan dalam permintaan Place Autocomplete
  3. Parameter fields yang menentukan kolom Basic Data seperti alamat dan geometri

Pertimbangkan untuk menunda permintaan Place Autocomplete
Anda dapat menggunakan strategi seperti menunda permintaan Place Autocomplete hingga pengguna mengetik dalam tiga atau empat karakter pertama, sehingga aplikasi Anda membuat permintaan yang lebih sedikit. Misalnya, membuat permintaan Place Autocomplete untuk setiap karakter setelah pengguna mengetik karakter ketiga berarti jika pengguna mengetik tujuh karakter, lalu memilih prediksi yang telah Anda buatkan untuknya satu permintaan Geocoding API, biaya total akan menjadi $0,01632 (4 * $0,00283 Autocomplete Per Request + $0,005 Geocoding).1

Jika permintaan yang tertunda dapat menghasilkan permintaan terprogram rata-rata di bawah empat, Anda dapat mengikuti panduan ini untuk penerapan Place Autocomplete yang berperforma dengan Geocoding API. Perhatikan bahwa permintaan yang tertunda dapat dianggap sebagai latensi oleh pengguna yang mungkin berharap melihat prediksi dengan setiap karakter baru yang mereka ketik.

Pertimbangkan untuk menerapkan praktik terbaik performa untuk membantu pengguna Anda mendapatkan prediksi yang mereka cari dalam karakter yang lebih sedikit.


  1. Biaya yang tercantum di sini adalah dalam USD. Lihat halaman Billing di Google Maps Platform untuk mendapatkan informasi harga selengkapnya.

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 dengan 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 mengharapkan pengguna 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 jika sebaiknya kembali ke Geocoding API meliputi:
    • Pengguna yang memasukkan alamat subpremis di negara selain Australia, Selandia Baru, atau Kanada. Misalnya, alamat AS "123 Bowdoin St #456, Boston MA, USA" tidak didukung oleh Autocomplete. (Autocomplete hanya mendukung alamat subpremis di Australia, Selandia Baru, dan Kanada. Format alamat yang didukung di tiga negara ini meliputi "9/321 Pitt Street, Sydney, New South Wales, Australia" atau "14/19 Langana Avenue, Browns Bay, Auckland, New Zealand" atau "145-112 Renfrew Dr, Markham, Ontario, Canada".)
    • 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 error dapat terjadi, sebagian besar error yang mungkin dialami aplikasi Anda biasanya disebabkan oleh error konfigurasi (misalnya, kunci API yang salah digunakan, atau kunci API salah dikonfigurasi), atau error kuota (aplikasi Anda telah melampaui kuotanya). Lihat Batas Penggunaan untuk mengetahui informasi lebih lanjut tentang kuota.

Error yang terjadi dalam penggunaan kontrol pelengkapan otomatis ditampilkan dalam callback onActivityResult(). Panggil Autocomplete.getStatus() untuk mendapatkan pesan status hasil.