Anda sudah siap!

Untuk mulai mengembangkan, masuklah ke dokumentasi developer kami.

Aktifkan Google Places API for Android

Untuk membantu Anda memulai, kami akan memandu Anda melalui Google Developers Console untuk melakukan beberapa hal terlebih dahulu:

  1. Buat atau pilih sebuah proyek
  2. Aktifkan Google Places API for Android
  3. Buat kunci yang sesuai
Lanjutkan

Place Autocomplete

Layanan pelengkapan otomatis dalam Google Places API for Android mengembalikan prediksi tempat sebagai respons terhadap kueri penelusuran pengguna. Saat pengguna mengetikkan, layanan pelengkapan otomatis akan mengembalikan usulan untuk tempat seperti bisnis, alamat, dan tempat menarik.

Anda bisa menambahkan pelengkapan otomatis ke aplikasi dengan cara berikut:

Tambahkan widget pelengkapan otomatis

Widget pelengkapan otomatis adalah sebuah dialog penelusuran dengan fungsionalitas pelengkapan otomatis bawaan. Saat pengguna memasukkan istilah penelusuran, widget tersebut akan menampilkan daftar pilihan tempat yang telah diprediksi. Bila pengguna telah membuat pilihan, sebuah instance Place akan dikembalikan, yang kemudian bisa digunakan aplikasi Anda untuk mendapatkan detail tentang tempat yang dipilih.

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

Opsi 1: Sematkan PlaceAutocompleteFragment atau SupportPlaceAutocompleteFragment

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

  1. Tambahkan fragmen ke layout XML aktivitas Anda.
  2. Tambahkan listener ke aktivitas atau fragmen Anda.

Tambahkan PlaceAutocompleteFragment ke aktivitas

Untuk menambahkan PlaceAutocompleteFragment ke aktivitas, tambahkan fragmen baru bernama com.google.android.gms.location.places.ui.PlaceAutocompleteFragment ke layout XML. Misalnya:

<fragment
  android:id="@+id/place_autocomplete_fragment"
  android:layout_width="match_parent"
  android:layout_height="wrap_content"
  android:name="com.google.android.gms.location.places.ui.PlaceAutocompleteFragment"
  />

Catatan: Secara default, fragmen tidak memiliki border atau latar belakang. Untuk menyediakan penampilan visual yang konsisten, sarangkan fragmen dalam elemen layout lain misalnya CardView.

Menambahkan PlaceSelectionListener ke aktivitas

Penanganan PlaceSelectionListener mengembalikan sebuah tempat sebagai respons terhadap pilihan pengguna. Kode berikut menampilkan pembuatan referensi ke fragmen dan menambahkan listener ke PlaceAutocompleteFragment Anda:

PlaceAutocompleteFragment autocompleteFragment = (PlaceAutocompleteFragment)
getFragmentManager().findFragmentById(R.id.place_autocomplete_fragment);

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

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

Gunakan SupportPlaceAutocompleteFragment (platform lama)

Google Places API memerlukan API level 12 atau yang lebih tinggi untuk dukungan objek PlaceAutocompleteFragment. Jika Anda menargetkan sebuah aplikasi yang lebih rendah dari API level 12, Anda bisa mengakses fungsionalitas yang sama melalui kelas SupportPlaceAutocompleteFragment. Anda juga harus menyertakan [Pustaka Dukungan] Android v4 (https://developer.android.com/tools/support-library/setup.html). Untuk mendukung Android versi sebelum API level 12, ikuti langkah-langkah ini:

  • Perluas FragmentActivity atau AppCompatActivity dalam aktivitas utama Anda.
  • Gunakan SupportPlaceAutocompleteFragment sebagai ganti PlaceAutocompleteFragment.
  • Gunakan getSupportFragmentManager() sebagai ganti getFragmentManager().

Opsi 2: Gunakan maksud untuk meluncurkan aktivitas pelengkapan otomatis

Jika Anda ingin agar aplikasi menggunakan alur navigasional yang berbeda (misalnya, untuk memicu pengalaman pelengkapan otomatis dari iko, bukan dari bidang penelusuran), aplikasi Anda bisa meluncurkan pelengkapan otomatis dengan menggunakan maksud.

Catatan: Langkah-langkah ini tidak dibutuhkan jika Anda menyematkan fragmen.

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

  1. Gunakan PlaceAutocomplete.IntentBuilder untuk membuat sebuah maksud, dengan meneruskan mode PlaceAutocomplete yang diinginkan. Maksud tersebut harus memanggil startActivityForResult, yang meneruskan kode permintaan yang mengidentifikasi maksud Anda.
  2. Ganti callback onActivityResult untuk menerima tempat yang dipilih.

Membuat maksud pelengkapan otomatis

Contoh di bawah ini menampilkan penggunaan PlaceAutocomplete.IntentBuilder untuk membuat maksud yang akan meluncurkan widget pelengkapan otomatis sebagai sebuah maksud:

int PLACE_AUTOCOMPLETE_REQUEST_CODE = 1;
...
try {
    Intent intent =
            new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                    .build(this);
    startActivityForResult(intent, PLACE_AUTOCOMPLETE_REQUEST_CODE);
} catch (GooglePlayServicesRepairableException e) {
    // TODO: Handle the error.
} catch (GooglePlayServicesNotAvailableException e) {
    // TODO: Handle the error.
}

Saat menggunakan maksud untuk meluncurkan widget pelengkapan otomatis, Anda bisa memilih dari beberapa mode tampilan layar penuh atau overlay. Tangkapan layar berikut menampilkan setiap mode tampilan masing-masing:

When displayed in overlay mode, the autocomplete widget appears superimposed over the calling UI.
Gambar 1: Widget pelengkapan otomatis di mode overlay (MODE_OVERLAY)
When displayed in fullscreen mode, the autocomplete widget fills the entire screen.
Gambar 2: Widget pelengkapan otomatis di mode layar penuh (MODE_FULLSCREEN)

Mengganti callback onActivityResult

Untuk menerima notifikasi bila pengguna telah memilih tempat, aplikasi Anda harus mengganti onActivityResult() aktivitas, yang memeriksa kode permintaan yang Anda teruskan untuk maksud, seperti yang ditampilkan dalam contoh berikut.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
    if (requestCode == PLACE_AUTOCOMPLETE_REQUEST_CODE) {
        if (resultCode == RESULT_OK) {
            Place place = PlaceAutocomplete.getPlace(this, data);
            Log.i(TAG, "Place: " + place.getName());
        } else if (resultCode == PlaceAutocomplete.RESULT_ERROR) {
            Status status = PlaceAutocomplete.getStatus(this, data);
            // TODO: Handle the error.
            Log.i(TAG, status.getStatusMessage());

        } else if (resultCode == RESULT_CANCELED) {
            // The user canceled the operation.
        }
    }
}

Batasi hasil pelengkapan otomatis

Anda bisa menyetel widget pelengkapan otomatis untuk mencondongkan hasil ke region geografis tertentu, dan/atau memfilter hasil ke satu atau beberapa tipe tempat.

Condongkan hasil ke region tertentu

Untuk mencondongkan hasil pelengkapan otomatis ke region geografis tertentu:

  • Panggil setBoundsBias() instance PlaceAutocompleteFragment aplikasi Anda, atau instance IntentBuilder, dengan meneruskan LatLngBounds. Contoh kode berikut menampilkan pemanggilan setBoundsBias() pada sebuah instance fragmen untuk mencondongkan usulan pelengkapan otomatisnya ke region Sydney, Australia.
autocompleteFragment.setBoundsBias(new LatLngBounds(
        new LatLng(-33.880490, 151.184363),
        new LatLng(-33.858754, 151.229596)));

Filter hasil menurut tipe tempat

Untuk memfilter hasil pelengkapan otomatis ke tipe tempat tertentu, panggil AutocompleteFilter.Builder untuk membuat AutocompleteFilter baru, dengan memanggil setTypeFilter() untuk menyetel filter yang akan digunakan. Kemudian, teruskan filter ke fragmen atau maksud.

Contoh kode berikut menampilkan setelan AutocompleteFilter pada PlaceAutocompleteFragment untuk menyetel filter yang hanya mengembalikan hasil dengan alamat akurat.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

autocompleteFragment.setFilter(typeFilter);

Contoh kode berikut menampilkan setelan AutocompleteFilter pada maksud untuk menyetel filter yang hanya mengembalikan hasil dengan alamat akurat.

AutocompleteFilter typeFilter = new AutocompleteFilter.Builder()
        .setTypeFilter(AutocompleteFilter.TYPE_FILTER_ADDRESS)
        .build();

Intent intent =
        new PlaceAutocomplete.IntentBuilder(PlaceAutocomplete.MODE_FULLSCREEN)
                .setFilter(typeFilter)
                .build(this);

Untuk informasi tentang tipe tempat, lihat panduan tipe tempat, dan AutocompleteFilter.Builder.

Mendapatkan prediksi tempat lewat program

Anda bisa membuat UI penelusuran khusus sebagai alternatif untuk UI yang disediakan oleh widget pelengkapan otomatis. Caranya, aplikasi Anda harus mendapatkan prediksi tempat lewat program. Aplikasi Anda bisa mendapatkan daftar nama tempat dan/atau alamat yang diprediksi dari layanan pelengkapan otomatis dengan memanggil GeoDataApi.getAutocompletePredictions(), yang meneruskan parameter berikut:

  • Diperlukan: String query berisi teks yang diketikkan oleh pengguna.
  • Diperlukan: Objek LatLngBounds mencondongkan hasil ke area tertentu yang ditetapkan oleh batas garis lintang dan garis bujur.
  • Opsional: AutocompleteFilter berisi satu set tipe tempat, yang bisa Anda gunakan untuk membatasi hasil pada satu atau beberapa tipe tempat. Tipe tempat berikut ini didukung:

    • TYPE_FILTER_NONE – Filter kosong; semua hasil dikembalikan.
    • TYPE_FILTER_GEOCODE – Hanya mengembalikan hasil geocoding, bukan bisnis. Gunakan permintaan ini untuk menghilangkan kerancuan hasil bila lokasi yang ditetapkan mungkin tidak pasti.
    • TYPE_FILTER_ADDRESS – Hanya mengembalikan hasil pelengkapan otomatis dengan alamat yang akurat. Gunakan tipe ini bila Anda mengetahui pengguna sedang mencari alamat yang ditetapkan secara lengkap.
    • TYPE_FILTER_ESTABLISHMENT – Hanya mengembalikan tempat yang berupa bisnis.
    • TYPE_FILTER_REGIONS – Hanya mengembalikan tempat yang cocok dengan salah satu tipe berikut:

      • locality
      • sublocality
      • postal_code
      • country
      • administrative_area_level_1
      • administrative_area_level_2
    • TYPE_FILTER_CITIES – Hanya mengembalikan hasil yang cocok dengan locality atau administrative_area_level_3.

Untuk informasi tentang tipe tempat, lihat panduan tipe tempat, dan AutocompleteFilter.Builder.

Contoh di bawah ini menampilkan panggilan yang disederhanakan untuk GeoDataApi.getAutocompletePredictions(). Untuk contoh lengkap, lihat aplikasi contoh.

PendingResult<AutocompletePredictionBuffer> result =
    Places.GeoDataApi.getAutocompletePredictions(mGoogleApiClient, query,
        bounds, autocompleteFilter);

API mengembalikan AutocompletePredictionBuffer dalam PendingResult. AutocompletePredictionBuffer berisi daftar objek AutocompletePrediction yang menyatakan tempat-tempat yang diprediksi. Buffer mungkin kosong, jika tidak ada tempat yang diketahui sesuai dengan kueri dan kriteria filter.

Catatan: Untuk mencegah kebocoran memori, Anda harus melepaskan objek AutocompletePredictionBuffer bila aplikasi Anda tidak lagi membutuhkannya. Baca selengkapnya tentang menangani buffer.

Untuk setiap tempat yang diprediksi, Anda bisa memanggil metode berikut untuk mengambil detail tempat:

  • getFullText(CharacterStyle matchStyle) mengembalikan teks lengkap dari keterangan tempat. Ini adalah kombinasi dari teks utama dan teks sekunder. Contoh: "Eiffel Tower, Avenue Anatole France, Paris, France". Sebagai tambahan, proses ini metode memungkinkan Anda menyoroti bagian keterangan yang cocok dengan penelusuran dengan gaya pilihan Anda, menggunakan CharacterStyle. Parameter CharacterStyle adalah opsional. Setel ke nol jika Anda tidak perlu menyorotinya.
  • getPrimaryText(CharacterStyle matchStyle) mengembalikan teks utama yang menjelaskan tempat. Ini biasanya adalah nama tempat tersebut. Contoh: "Eiffel Tower", dan "123 Pitt Street".
  • getSecondaryText(CharacterStyle matchStyle) mengembalikan teks pendukung dari keterangan tempat. Ini berguna, misalnya, sebagai baris kedua saat menampilkan prediksi pelengkapan otomatis. Contoh: "Avenue Anatole France, Paris, France", dan "Sydney, New South Wales".
  • getPlaceId() mengembalikan ID tempat yang diprediksi. ID tempat adalah identifier tekstual yang secara unik mengidentifikasi tempat, yang bisa Anda gunakan untuk mengambil objek Place lagi nanti. Untuk informasi selengkapnya tentang ID tempat di Google Places API for Android, lihat ID Tempat dan Detail. Untuk informasi umum tentang ID tempat, lihat ringkasan ID tempat.
  • getPlaceTypes() mengembalikan daftar tipe tempat yang dikaitkan dengan tempat ini.

Batas penggunaan

  • Penggunaan metode [GeoDataApi.getAutocompletePredictions()](/android/reference/com/google/android/gms/location/places/GeoDataApi.html#getAutocompletePredictions(com.google.android.gms.common.api.GoogleApiClient, java.lang.String, com.google.android.gms.maps.model.LatLngBounds, com.google.android.gms.location.places.AutocompleteFilter) tunduk pada batas kueri bertingkat. Lihat dokumentasi mengenai Batas Penggunaan.

Tampilkan atribusi dalam aplikasi Anda

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

Untuk detail selengkapnya, lihat dokumentasi mengenai atribusi.

Pemecahan Masalah

Walaupun berbagai macam kesalahan bisa terjadi, mayoritas kesalahan yang mungkin dialami aplikasi Anda biasanya adalah disebabkan oleh kesalahan konfigurasi (misalnya, kunci API yang digunakan salah, atau kunci API salah konfigurasinya), atau kesalahan kuota (aplikasi Anda telah melebihi kuotanya). Lihat Batas Penggunaan untuk informasi selengkapnya tentang kuota.

Kesalahan yang terjadi dalam penggunaan kontrol pelengkapan otomatis dikembalikan dalam callback onActivityResult(). Panggil PlaceAutocomplete.getStatus() untuk mendapatkan pesan status hasil.

Kirim masukan tentang...

location_on
Google Places API for Android