Pelengkapan Otomatis (Baru)

Autocomplete (Baru) menampilkan prediksi tempat sebagai respons terhadap permintaan yang mencakup string penelusuran teks dan batas geografis yang mengontrol area penelusuran. Autocomplete dapat mencocokkan kata dan substring lengkap dari input, yang me-resolve nama tempat, alamat, dan Plus Codes. Aplikasi Anda dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat dan kueri secara real time.

Misalnya, Anda memanggil Autocomplete menggunakan input string yang berisi input pengguna parsial, "pizza Sisilia", dengan area penelusuran terbatas di 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 dirancang untuk ditampilkan kepada pengguna guna membantu mereka memilih tempat yang diinginkan. Anda dapat membuat permintaan Place Details (Baru) untuk mendapatkan informasi selengkapnya tentang prediksi tempat yang ditampilkan.

Anda dapat mengintegrasikan fungsi Pelengkapan Otomatis (Baru) ke dalam aplikasi Anda dengan dua cara utama:

• Menambahkan widget Place Autocomplete: Menyediakan pengalaman pelengkapan otomatis penelusuran siap pakai melalui class PlaceAutocomplete yang menampilkan prediksi saat pengguna mengetik.
• Mendapatkan prediksi tempat secara terprogram: Panggil API secara langsung untuk mengambil prediksi dan menampilkannya di antarmuka pengguna kustom.

Menambahkan widget Place Autocomplete

Untuk memberikan pengalaman pelengkapan otomatis tempat yang konsisten dengan lebih mudah, Anda dapat menambahkan widget Place Autocomplete ke aplikasi Anda. Widget ini menyediakan antarmuka khusus layar penuh yang menangani input pengguna dan menampilkan prediksi tempat kepada pengguna sekaligus menampilkan objek AutocompletePrediction ke aplikasi. Kemudian, Anda dapat membuat permintaan Place Details (Baru) untuk mendapatkan informasi tambahan tentang prediksi tempat.

Seperti saat mendapatkan prediksi tempat secara terprogram, widget Place Autocomplete memungkinkan Anda menggunakan token sesi untuk mengelompokkan permintaan pelengkapan otomatis ke dalam sesi untuk tujuan penagihan. Anda dapat meneruskan token sesi saat membuat intent untuk widget dengan memanggil setAutocompleteSessionToken(). Jika Anda tidak memberikan token sesi, widget akan membuatnya untuk Anda, yang dapat Anda akses dengan memanggil getSessionTokenFromIntent(). Untuk mengetahui informasi selengkapnya tentang cara menggunakan token sesi, lihat artikel Tentang token sesi.

Untuk menambahkan widget Place Autocomplete ke aplikasi Anda:

1. (Opsional) Tentukan token sesi. Jika Anda tidak memberikan token sesi, widget akan membuatnya untuk Anda.

2. Tentukan autocompleteIntent dengan parameter yang diinginkan dan token sesi Anda.

3. Tentukan ActivityResultLauncher untuk StartActivityForResult. Peluncur ini akan menangani hasil yang ditampilkan dari aktivitas pelengkapan otomatis.

4. Tangani hasilnya di callback ActivityResultLauncher. Hal ini melibatkan pengekstrakan AutocompletePrediction dan AutocompleteSessionToken (jika Anda belum menyediakannya sendiri), penanganan error, dan secara opsional membuat permintaan fetchPlace() untuk mendapatkan detail tambahan tentang suatu tempat.

5. Luncurkan intent menggunakan placeAutocompleteActivityResultLauncher

Contoh berikut menunjukkan cara menambahkan widget Place Autocomplete menggunakan Kotlin dan Java:

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key)

// Optional, create a session token for Autocomplete request and the followup FetchPlace request.
val sessionToken: AutocompleteSessionToken = AutocompleteSessionToken.newInstance()

val autocompleteIntent: Intent =
    PlaceAutocomplete.createIntent(this) {
        // ... provide input params for origin, countries, types filter ...
        setAutocompleteSessionToken(sessionToken)
    }

val placeAutocompleteActivityResultLauncher: ActivityResultLauncher<Intent> =
    registerForActivityResult(ActivityResultContracts.StartActivityForResult()) { result: ActivityResult ->
        val intent = result.data
        if (intent != null && result.resultCode == PlaceAutocompleteActivity.RESULT_OK) {
            // get prediction object
            val prediction: AutocompletePrediction? =
                PlaceAutocomplete.getPredictionFromIntent(intent!!)

            // get session token
            val sessionToken: AutocompleteSessionToken? =
                PlaceAutocomplete.getSessionTokenFromIntent(intent!!)

            // create PlacesClient to make FetchPlace request (optional)
            val placesClient: PlacesClient = Places.createClient(this)
            val response =
                placesClient.awaitFetchPlace(prediction.placeId, Field.DISPLAY_NAME)
                {
                    sessionToken = sessionToken // optional
                }
        }
    }

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent)

// Provide the API key that has enabled "Places API (New)" in the Google Cloud Console.
Places.initializeWithNewPlacesApiEnabled(/* Context= */ context, /* API Key= */ key);

// Optional, create a session token for Autocomplete request and the followup FetchPlace request
AutocompleteSessionToken sessionToken = AutocompleteSessionToken.newInstance();

Intent autocompleteIntent =
    new PlaceAutocomplete.IntentBuilder()
        // ... set input params for origin, countries, types filter ...
        .setSessionToken(sessionToken) // optional
        .build(this);

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
    registerForActivityResult(
        new ActivityResultContracts.StartActivityForResult(),
        new ActivityResultCallback<ActivityResult>() {
            @Override
            public void onActivityResult(ActivityResult result) {
                Intent intent = result.getData();
                if (result.getResultCode() == PlaceAutocompleteActivity.RESULT_OK) {
                    // get prediction object
                    AutocompletePrediction prediction =
                        PlaceAutocomplete.getPredictionFromIntent(
                            Preconditions.checkNotNull(intent));

                    // get session token
                    AutocompleteSessionToken sessionToken =
                        PlaceAutocomplete.getSessionTokenFromIntent(
                            Preconditions.checkNotNull(intent));

                    // create PlacesClient to make FetchPlace request (optional)
                    PlacesClient placesClient = Places.createClient(this);
                    FetchPlaceRequest request =
                        FetchPlaceRequest.builder(prediction.getPlaceId(),
                            Arrays.asList(Field.DISPLAY_NAME))
                            .setSessionToken(sessionToken).build();
                    Task<FetchPlaceResponse> task = placesClient.fetchPlace(request);
                }
            }
        }
    );

// Launch Activity
placeAutocompleteActivityResultLauncher.launch(autocompleteIntent);

Menyesuaikan tema

Saat membuat instance pengalaman Pelengkapan Otomatis, Anda dapat menentukan tema yang menggantikan atribut gaya default. Anda dapat menyesuaikan warna, tipografi, jarak, batas, dan sudut komponen Place Autocomplete. Defaultnya adalah PlacesMaterialTheme. Atribut tema yang tidak diganti akan menggunakan gaya default.

Anda dapat menentukan penggantian tema di …/res/values/themes.xml. Contoh:

<?xml version="1.0" encoding="utf-8"?>
<resources>
  <style name="BrandedTheme" parent="PlacesMaterialTheme">
    <!-- Color tokens. -->
    <item name="placesColorOnNeutralContainer">#5300e8</item>
    <item name="placesColorOnNeutralContainerVariant">#ee6002</item>
    ...

    <!-- Typography tokens. -->
    <item name="placesTextAppearanceTitleLarge">@style/PlacesTextAppearance</item>
    <item name="placesTextAppearanceBodyMedium">@style/PlacesTextAppearance</item>
    ...

    <!-- Spacing tokens. -->
    <item name="placesSpacingSmall">6dp</item>
    <item name="placesSpacingMedium">12dp</item>
    ...

    <!-- Attribution tokens. -->
    <item name="placesColorAttributionLightTheme">white</item>
    <item name="placesColorAttributionDarkTheme">black</item>
  </style>
</resources>

Kemudian, Anda dapat mereferensikan gaya penggantian dengan memanggil setAutocompleteUiCustomization:

ActivityResultLauncher<Intent> placeAutocompleteActivityResultLauncher =
  registerForActivityResult(
    new ActivityResultContracts.StartActivityForResult(),
    new ActivityResultCallback<ActivityResult>() {
      @Override
      public void onActivityResult(ActivityResult result) {
        Intent intent = result.getData();
        if (intent != null) {
          AutocompletePrediction prediction =
            PlaceAutocomplete.getPredictionFromIntent(intent);
          AutocompleteSessionToken sessionToken =
            PlaceAutocomplete.getSessionTokenFromIntent(intent);
          Status status = PlaceAutocomplete.getResultStatusFromIntent(intent);
          ...
        }
      }
    }
  );

Intent placeAutocompleteIntent =
  new PlaceAutocomplete.IntentBuilder()
    .setInitialQuery("INSERT_QUERY_TEXT")
    .setOrigin(new LatLng(10.0, 10.0))
    ...

    .setAutocompleteUiCustomization(
      AutocompleteUiCustomization.builder()
        .listItemIcon(AutocompleteUiIcon.noIcon())
        .listDensity(AutocompleteListDensity.MULTI_LINE)
        .theme(R.style.BrandedTheme)
        .build())
  .build(this);

placeAutocompleteActivityResultLauncher.launch(placeAutocompleteIntent);

Mendapatkan prediksi tempat secara terprogram

Aplikasi Anda dapat memperoleh daftar nama dan/atau alamat tempat yang diprediksi dari API pelengkapan otomatis dengan memanggil PlacesClient.findAutocompletePredictions(), dengan 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 Pelengkapan Otomatis (Baru)

API menampilkan FindAutocompletePredictionsResponse dalam Task. FindAutocompletePredictionsResponse berisi daftar hingga lima objek AutocompletePrediction yang merepresentasikan 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 primer dan sekunder. Contoh: "Menara Eiffel, Avenue Anatole France, Paris, Prancis". Selain itu, metode ini memungkinkan Anda menandai bagian deskripsi yang cocok dengan penelusuran menggunakan gaya pilihan Anda, dengan CharacterStyle. Parameter CharacterStyle bersifat opsional. Tetapkan ke null jika Anda tidak memerlukan penyorotan.
• getPrimaryText(CharacterStyle) menampilkan teks utama yang mendeskripsikan suatu tempat. Ini biasanya adalah nama tempat. Contoh: "Menara Eiffel", dan "123 Pitt Street".
• getSecondaryText(CharacterStyle) menampilkan teks tambahan dari deskripsi tempat. Hal ini berguna, misalnya, sebagai baris kedua saat menampilkan prediksi pelengkapan otomatis. Contoh: "Avenue Anatole France, Paris, Prancis", 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 mengetahui informasi selengkapnya tentang ID tempat di Autocomplete, lihat Place Details (Baru). 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 akan ditelusuri. Tentukan kata dan substring lengkap, nama tempat, alamat, dan Plus Codes. Layanan Pelengkapan Otomatis (Baru) menampilkan bakal hasil berdasarkan string ini dan mengurutkan hasil berdasarkan relevansi yang terlihat.

  Untuk menetapkan parameter kueri, panggil metode setQuery() saat membuat 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.

  Suatu 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.
  • 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 hingga 15 nilai dua karakter ccTLD ("domain level teratas"). Jika tidak disertakan, tidak ada batasan yang diterapkan pada respons. Misalnya, untuk membatasi wilayah ke Jerman dan Prancis:

  Jika Anda menentukan locationRestriction dan includedRegionCodes, hasilnya terletak di area persimpangan 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, defaultnya adalah panjang kueri.

  Untuk menetapkan parameter offset input, panggil metode setInputOffset() saat membangun 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 penentuan region tempat hasil harus berada, dan bias lokasi sebagai penentuan region tempat hasil harus berada di dekatnya. 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 batasan, sehingga hasil di luar area yang ditentukan mungkin tetap ditampilkan.

    Untuk menyetel parameter bias lokasi, panggil metode setLocationBias() saat membangun 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 membuat objek FindAutocompletePredictionsRequest.

  Tentukan bias lokasi atau wilayah pembatasan lokasi sebagai Viewport 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:

    • Jika low = high, area pandang terdiri dari satu titik tersebut.
    • Jika low.longitude > high.longitude, rentang bujur akan dibalik (area pandang melintasi garis bujur 180 derajat).
    • Jika low.longitude = -180 derajat dan high.longitude = 180 derajat, area pandang mencakup semua bujur.
    • Jika low.longitude = 180 derajat dan high.longitude = -180 derajat, rentang bujur kosong.

    low dan high harus diisi, dan kotak yang ditampilkan tidak boleh kosong. Viewport kosong akan menyebabkan error.

• Asal

  Titik asal dari mana jarak garis lurus ke tujuan dihitung (diakses menggunakan getDistanceMeters()). Jika nilai ini tidak disertakan, jarak garis lurus tidak akan ditampilkan. Harus ditentukan sebagai koordinat lintang dan bujur:

  Untuk menyetel parameter asal, panggil metode setOrigin() saat membuat 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").

  Jika Anda menentukan kode wilayah yang tidak valid, API akan menampilkan error INVALID_ARGUMENT. Parameter 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 yang dibuat pengguna yang melacak panggilan Autocomplete (Baru)—baik panggilan yang dilakukan melalui widget maupun panggilan terprogram—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, 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 Detail Tempat untuk tempat yang dipilih oleh pengguna.

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

  Untuk mengetahui informasi selengkapnya, lihat Token sesi.

Contoh Pelengkapan Otomatis (Baru)

Menggunakan pembatasan lokasi dan preferensi lokasi

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

Menggunakan jenis utama

Gunakan parameter primary types untuk membatasi hasil dari permintaan agar berjenis 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 "Soccer" dan menggunakan parameter jenis utama untuk membatasi hasil ke tempat dengan 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 mencakup tempat dengan jenis yang mungkin tidak Anda inginkan, seperti "athletic_field".

Gunakan asal

Saat Anda menyertakan parameter origin dalam permintaan, yang ditentukan sebagai koordinat garis lintang dan bujur, API akan menyertakan jarak garis lurus dari asal ke tujuan dalam respons (dapat 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());
        })
    );

Pengoptimalan Pelengkapan Otomatis (Baru)

Bagian ini menjelaskan praktik terbaik untuk membantu Anda memaksimalkan layanan Autocomplete (Baru).

Berikut ini beberapa pedoman umum:

• Cara tercepat untuk mengembangkan antarmuka pengguna yang berfungsi baik adalah dengan menggunakan widget Autocomplete (Baru) Maps JavaScript API, widget Autocomplete (Baru) Places SDK for Android, atau widget Autocomplete (Baru) Places SDK for iOS.
• Pahami kolom data Pelengkapan Otomatis (Baru) 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 Autocomplete (Baru), gunakan mask kolom dalam widget Place Details (Baru) dan Autocomplete (Baru) agar hanya menampilkan kolom data Autocomplete (Baru) yang Anda butuhkan.

Pengoptimalan biaya lanjutan

Pertimbangkan implementasi Autocomplete (Baru) yang terprogram untuk mengakses SKU: Harga Permintaan Autocomplete dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details (Baru). 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 dengan biaya yang lebih murah daripada panggilan Place Details (Baru).
• Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete (Baru) 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 Autocomplete (Baru):

• Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Pelengkapan Otomatis (Baru) Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
• Jika Autocomplete (Baru) disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
• Jika pengguna tidak memilih salah satu prediksi Autocomplete (Baru), 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 Place Details (Baru). Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
  Skenario lain saat Anda sebaiknya beralih kembali ke Geocoding API mencakup:
  • Pengguna memasukkan alamat sub-tempat, seperti alamat untuk unit atau apartemen tertentu dalam sebuah gedung. Misalnya, alamat Ceko "Stroupežnického 3191/17, Praha" akan menghasilkan prediksi parsial di Autocomplete (Baru).
  • 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.

Penyesuaian lokasi

Membiaskan hasil ke area tertentu dengan meneruskan parameter location dan parameter radius. Tindakan ini menginstruksikan Autocomplete (Baru) untuk memilih menampilkan hasil dalam area yang ditentukan. Hasil di luar area yang ditentukan mungkin tetap ditampilkan. Anda dapat menggunakan parameter components untuk memfilter hasil guna menampilkan hanya tempat-tempat di negara tertentu.

Membatasi lokasi

Batasi hasil ke area tertentu dengan meneruskan parameter locationRestriction.

Anda juga dapat membatasi hasil ke wilayah yang ditentukan oleh parameter location dan radius, dengan menambahkan parameter locationRestriction. Hal ini menginstruksikan Autocomplete (Baru) untuk menampilkan hanya hasil dalam wilayah tersebut.