Place Autocomplete

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

Pengantar

Autocomplete adalah fitur library Places di Maps JavaScript API. Anda dapat menggunakan pelengkapan otomatis untuk memberi aplikasi Anda perilaku prediksi penelusuran di kolom penelusuran Google Maps. Layanan pelengkapan otomatis dapat mencocokkan kata dan substring lengkap, menyelesaikan nama tempat, alamat, dan kode plus. Oleh karena itu, aplikasi dapat mengirim kueri saat pengguna mengetik, untuk memberikan prediksi tempat dengan cepat.

Memulai

Sebelum menggunakan Places Library di Maps JavaScript API, pastikan terlebih dahulu bahwa Places API diaktifkan di Google Cloud Console, dalam project yang sama dengan yang Anda siapkan untuk Maps JavaScript API.

Untuk menampilkan daftar API yang telah diaktifkan:

  1. Buka Google Cloud Console.
  2. Klik tombol Select a project, lalu pilih project yang sama dengan yang Anda siapkan untuk Maps JavaScript API dan klik Open.
  3. Dari daftar API di Dasbor, cari Places API.
  4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak tercantum, aktifkan:
    1. Di bagian atas halaman, pilih ENABLE API untuk menampilkan tab Library. Atau, dari menu samping kiri, pilih Library.
    2. Telusuri Places API, lalu pilih dari daftar hasil.
    3. Pilih AKTIFKAN. Setelah proses ini selesai, Places API akan muncul dalam daftar API di Dashboard.

Memuat Pustaka

Layanan Places adalah library mandiri, terpisah dari kode utama Maps JavaScript API. Untuk menggunakan fungsi yang ada dalam library ini, Anda harus terlebih dahulu memuatnya menggunakan parameter libraries di URL bootstrap Maps API:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Lihat Ringkasan Library untuk informasi selengkapnya.

Ringkasan kelas

API ini menawarkan dua jenis widget pelengkapan otomatis, yang masing-masing dapat Anda tambahkan melalui class Autocomplete dan SearchBox. Selain itu, Anda dapat menggunakan class AutocompleteService untuk mengambil hasil pelengkapan otomatis secara terprogram (lihat Referensi Maps JavaScript API: Class AutocompleteService).

Di bawah ini adalah rangkuman kelas-kelas yang tersedia:

  • Autocomplete menambahkan kolom input teks ke halaman web Anda, dan memantau kolom tersebut untuk entri karakter. Saat pengguna memasukkan teks, pelengkapan otomatis menampilkan prediksi tempat dalam bentuk daftar pilihan drop-down. Saat pengguna memilih tempat dari daftar, informasi tentang tempat tersebut akan ditampilkan ke objek pelengkapan otomatis, dan dapat diambil oleh aplikasi Anda. Lihat detailnya di bawah.
    Kolom teks pelengkapan otomatis, dan daftar pilihan prediksi tempat yang diberikan saat pengguna memasukkan kueri penelusuran.
    Gambar 1: Pelengkapan otomatis untuk kolom teks dan daftar pilihan
    Sebuah formulir alamat lengkap.
    Gambar 2: Formulir alamat yang telah diisi
  • SearchBox menambahkan kolom input teks ke halaman web Anda, dengan cara yang sama seperti Autocomplete. Perbedaannya adalah sebagai berikut:
    • Perbedaan utamanya terletak pada hasil yang muncul dalam daftar pilihan. SearchBox menyediakan daftar prediksi tambahan yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) dan istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza di new', daftar pilihan dapat menyertakan frasa 'pizza di New York, NY' serta nama berbagai gerai pizza.
    • SearchBox menawarkan lebih sedikit opsi daripada Autocomplete untuk membatasi penelusuran. Pada versi pertama, Anda dapat mencondongkan penelusuran ke LatLngBounds tertentu. Pada opsi kedua, Anda dapat membatasi penelusuran ke negara dan jenis tempat tertentu, serta menyetel batasnya. Untuk informasi selengkapnya, lihat di bawah.
    Sebuah formulir alamat lengkap.
    Gambar 3: Kotak Penelusuran menyajikan istilah penelusuran dan prediksi tempat.
    Lihat detailnya di bawah.
  • Anda dapat membuat objek AutocompleteService untuk mengambil prediksi secara terprogram. Panggil getPlacePredictions() untuk mengambil data tempat yang cocok, atau panggil getQueryPredictions() untuk mengambil data tempat yang cocok beserta istilah penelusuran yang disarankan. Catatan: AutocompleteService tidak menambahkan kontrol UI apa pun. Sebagai gantinya, metode di atas mengembalikan larik objek prediksi. Setiap objek prediksi berisi teks prediksi, serta informasi referensi dan detail tentang kecocokan hasil dengan input pengguna. Lihat detailnya di bawah.

Menambahkan widget Autocomplete

Widget Autocomplete membuat kolom input teks di halaman web Anda, memberikan prediksi tempat dalam daftar pilihan UI, dan menampilkan detail tempat sebagai respons terhadap permintaan getPlace(). Setiap entri dalam daftar yang dipilih mewakili satu tempat (seperti yang ditentukan oleh Places API).

Konstruktor Autocomplete mengambil dua argumen:

  • Elemen input HTML jenis text. Ini adalah kolom input tempat layanan pelengkapan otomatis akan memantau dan melampirkan hasilnya.
  • Argumen AutocompleteOptions opsional, yang dapat berisi properti berikut:
    • Array data fields yang akan disertakan dalam respons Place Details untuk PlaceResult yang dipilih pengguna. Jika properti tidak ditetapkan atau jika ['ALL'] diteruskan, semua kolom yang tersedia akan ditampilkan dan ditagih untuk (ini tidak direkomendasikan untuk deployment produksi). Untuk mengetahui daftar kolom, lihat PlaceResult.
    • Array types yang menentukan jenis eksplisit atau koleksi jenis, seperti yang tercantum dalam jenis yang didukung. Jika tidak ada jenis yang ditentukan, semua jenis akan ditampilkan.
    • bounds adalah objek google.maps.LatLngBounds yang menentukan area untuk menelusuri tempat. Hasilnya dicondongkan ke, tetapi tidak terbatas pada, tempat yang berada dalam batas ini.
    • strictBounds adalah boolean yang menentukan apakah API hanya boleh menampilkan tempat yang benar-benar berada dalam region yang ditentukan oleh bounds tertentu. API tidak menampilkan hasil di luar region ini meskipun cocok dengan input pengguna.
    • componentRestrictions dapat digunakan untuk membatasi hasil ke grup tertentu. Saat ini, Anda dapat menggunakan componentRestrictions untuk memfilter hingga 5 negara. Negara harus diteruskan sebagai kode negara yang kompatibel dengan ISO 3166-1 Alpha-2 dua karakter. Beberapa negara harus diteruskan sebagai daftar kode negara.

      Catatan: Jika Anda menerima hasil yang tidak terduga dengan kode negara, pastikan bahwa Anda menggunakan kode yang mencakup negara, wilayah dependensi, dan area khusus dari kepentingan geografis yang Anda inginkan. Anda dapat menemukan informasi kode di Wikipedia: Daftar kode negara ISO 3166 atau Platform Penjelajahan Online ISO.

    • placeIdOnly dapat digunakan untuk memerintahkan widget Autocomplete agar hanya mengambil ID Tempat. Saat memanggil getPlace() pada objek Autocomplete, PlaceResult yang tersedia hanya akan memiliki properti place id, types, dan name yang ditetapkan. Anda dapat menggunakan ID tempat yang ditampilkan dengan panggilan ke layanan Places, Geocoding, Directions, atau Distance Matrix.

Membatasi prediksi Autocomplete

Secara default, Place Autocomplete menampilkan semua jenis tempat, yang bias untuk prediksi di dekat lokasi pengguna, dan mengambil semua kolom data yang tersedia untuk tempat yang dipilih pengguna. Setel opsi Place Autocomplete untuk memberikan prediksi yang lebih relevan berdasarkan kasus penggunaan Anda.

Tetapkan opsi saat pembuatan

Konstruktor Autocomplete menerima parameter AutocompleteOptions untuk menetapkan batasan pada pembuatan widget. Contoh berikut menetapkan opsi bounds, componentRestrictions, dan types untuk meminta jenis tempat establishment, yang memilih tempat dalam area geografis yang ditentukan dan membatasi prediksi hanya untuk tempat di Amerika Serikat. Menetapkan opsi fields akan menentukan informasi yang akan ditampilkan tentang tempat yang dipilih pengguna.

Panggil setOptions() untuk mengubah nilai opsi untuk widget yang ada.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Menentukan kolom data

Tentukan kolom data yang tidak perlu ditagih untuk SKU Data Tempat yang tidak Anda butuhkan. Sertakan properti fields dalam AutocompleteOptions yang diteruskan ke konstruktor widget, seperti yang ditunjukkan dalam contoh sebelumnya, atau panggil setFields() pada objek Autocomplete yang ada.

autocomplete.setFields(["place_id", "geometry", "name"]);

Menentukan bias dan batas area penelusuran untuk Autocomplete

Anda dapat mencondongkan hasil pelengkapan otomatis untuk mengutamakan perkiraan lokasi atau area dengan cara berikut:

  • Menetapkan batas pada pembuatan objek Autocomplete.
  • Mengubah batas Autocomplete yang sudah ada.
  • Tetapkan batas ke area pandang peta.
  • Membatasi penelusuran pada batas.
  • Membatasi penelusuran pada negara tertentu.

Contoh sebelumnya menunjukkan penetapan batas saat pembuatan. Contoh berikut menunjukkan teknik bias lainnya.

Mengubah batas yang ada pada Autocomplete

Panggil setBounds() untuk mengubah area penelusuran pada Autocomplete yang ada ke batas persegi panjang.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Tetapkan batas ke area pandang peta

Gunakan bindTo() untuk mencondongkan hasilnya ke area pandang peta, meskipun area pandang berubah.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Gunakan unbind() untuk melepaskan prediksi Autocomplete dari area pandang peta.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

Lihat contoh

Batasi penelusuran hingga batas saat ini

Tetapkan opsi strictBounds untuk membatasi hasil pada batas saat ini, baik berdasarkan area pandang peta maupun batas persegi panjang.

autocomplete.setOptions({ strictBounds: true });
Membatasi prediksi ke negara tertentu

Gunakan opsi componentRestrictions atau panggil setComponentRestrictions() untuk membatasi penelusuran pelengkapan otomatis pada kumpulan spesifik hingga lima negara.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

Lihat contoh

Batasi jenis tempat

Gunakan opsi types atau panggil setTypes() untuk membatasi prediksi ke jenis tempat tertentu. Batasan ini menentukan jenis atau koleksi jenis, seperti yang tercantum dalam Place Types. Jika tidak ada batasan yang ditentukan, semua jenis akan ditampilkan.

Untuk nilai opsi types atau nilai yang diteruskan ke setTypes(), Anda dapat menentukan:

  • Array yang berisi hingga lima nilai dari Tabel 1 atau Tabel 2 dari Jenis Tempat. Contoh:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    Atau:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Satu filter di Tabel 3 dari Jenis Tempat. Anda hanya dapat menentukan satu nilai dari Tabel 3.

Permintaan akan ditolak jika:

  • Anda menentukan lebih dari lima jenis.
  • Anda menentukan jenis yang tidak dikenal.
  • Anda mencampur semua jenis dari Tabel 1 atau Tabel 2 dengan filter apa pun dari Tabel 3.

Demo Places Autocomplete menunjukkan perbedaan prediksi di antara berbagai jenis tempat.

Buka demo

Mendapatkan informasi tempat

Saat pengguna memilih tempat dari prediksi yang dilampirkan ke kolom teks pelengkapan otomatis, layanan akan mengaktifkan peristiwa place_changed. Untuk mendapatkan detail tempat:

  1. Buat pengendali peristiwa untuk peristiwa place_changed, dan panggil addListener() pada objek Autocomplete untuk menambahkan pengendali.
  2. Panggil Autocomplete.getPlace() pada objek Autocomplete, untuk mengambil objek PlaceResult, yang kemudian dapat Anda gunakan untuk mendapatkan informasi selengkapnya tentang tempat yang dipilih.

Secara default, saat pengguna memilih tempat, pelengkapan otomatis menampilkan semua kolom data yang tersedia untuk tempat yang dipilih, dan Anda akan ditagih sesuai dengan itu. Gunakan Autocomplete.setFields() untuk menentukan kolom data tempat yang akan ditampilkan. Baca selengkapnya tentang objek PlaceResult, termasuk daftar kolom data tempat yang dapat Anda minta. Agar tidak membayar data yang tidak Anda perlukan, pastikan menggunakan Autocomplete.setFields() untuk menentukan data tempat yang akan digunakan saja.

Properti name berisi description dari prediksi Places Autocomplete. Anda dapat membaca selengkapnya tentang description di dokumentasi Places Autocomplete.

Untuk formulir alamat, sebaiknya dapatkan alamat dalam format terstruktur. Untuk menampilkan alamat terstruktur untuk tempat yang dipilih, panggil Autocomplete.setFields() dan tentukan kolom address_components.

Contoh berikut menggunakan pelengkapan otomatis untuk mengisi kolom di formulir alamat.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Lihat contoh

Menyesuaikan teks placeholder

Secara default, kolom teks yang dibuat oleh layanan pelengkapan otomatis berisi teks placeholder standar. Untuk mengubah teks, tetapkan atribut placeholder pada elemen input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Catatan: Teks placeholder default dilokalkan secara otomatis. Jika Anda menentukan nilai placeholder sendiri, Anda harus menangani pelokalan nilai tersebut dalam aplikasi Anda. Untuk informasi tentang cara Google Maps JavaScript API memilih bahasa yang akan digunakan, baca dokumentasi mengenai pelokalan.

Lihat Menata gaya widget Autocomplete dan SearchBox untuk menyesuaikan tampilan widget.

SearchBox memungkinkan pengguna melakukan penelusuran geografis berbasis teks, seperti 'pizza di New York' atau 'toko sepatu dekat robson Street'. Anda dapat melampirkan SearchBox ke kolom teks, dan saat teks dimasukkan, layanan akan menampilkan prediksi dalam bentuk menu pilihan drop-down.

SearchBox menyediakan daftar prediksi tambahan, yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) dan istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza di new', daftar pilihan dapat menyertakan frasa 'pizza di New York, NY' serta nama berbagai gerai pizza. Saat pengguna memilih tempat dari daftar, informasi tentang tempat tersebut akan ditampilkan ke objek SearchBox, dan dapat diambil oleh aplikasi Anda.

Konstruktor SearchBox mengambil dua argumen:

  • Elemen input HTML jenis text. Kolom input ini akan dipantau oleh layanan SearchBox dan melampirkan hasilnya.
  • Argumen options, yang dapat berisi properti bounds: bounds adalah objek google.maps.LatLngBounds yang menentukan area untuk menelusuri tempat. Hasilnya dicondongkan ke, tetapi tidak terbatas pada, tempat yang berada dalam batas ini.

Kode berikut menggunakan parameter batas untuk mencondongkan hasil ke tempat dalam area geografis tertentu, yang ditetapkan melalui koordinat garis lintang/bujur.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Mengubah area penelusuran untuk SearchBox

Untuk mengubah area penelusuran untuk SearchBox yang ada, panggil setBounds() pada objek SearchBox dan teruskan objek LatLngBounds yang relevan.

Lihat contoh

Mendapatkan informasi tempat

Saat pengguna memilih item dari prediksi yang dilampirkan ke kotak penelusuran, layanan akan mengaktifkan peristiwa places_changed. Anda dapat memanggil getPlaces() pada objek SearchBox, untuk mengambil array yang berisi beberapa prediksi, yang masing-masing merupakan objek PlaceResult.

Untuk informasi selengkapnya tentang objek PlaceResult, lihat dokumentasi tentang hasil detail tempat.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Lihat contoh

Lihat Menata gaya widget Autocomplete dan SearchBox untuk menyesuaikan tampilan widget.

Mengambil prediksi Layanan Place Autocomplete secara terprogram

Untuk mengambil prediksi secara terprogram, gunakan class AutocompleteService. AutocompleteService tidak menambahkan kontrol UI apa pun. Sebagai gantinya, metode ini menampilkan array objek prediksi, yang masing-masing berisi teks prediksi, informasi referensi, dan detail tentang kecocokan hasil dengan input pengguna. Cara ini berguna jika Anda menginginkan lebih banyak kontrol atas antarmuka pengguna daripada yang ditawarkan oleh Autocomplete dan SearchBox yang dijelaskan di atas.

AutocompleteService menampilkan metode berikut:

  • getPlacePredictions() menampilkan prediksi tempat. Catatan: A 'place' dapat berupa tempat usaha, lokasi geografis, atau lokasi menarik yang menonjol, seperti yang ditentukan oleh Places API.
  • getQueryPredictions() menampilkan daftar prediksi yang diperluas, yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) ditambah istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza di new', daftar pilihan dapat menyertakan frasa 'pizza di New York, NY' serta nama berbagai gerai pizza.

Kedua metode di atas menampilkan array objek prediksi dengan bentuk berikut:

  • description adalah prediksi yang cocok.
  • distance_meters adalah jarak dalam meter tempat dari AutocompletionRequest.origin yang ditentukan.
  • matched_substrings berisi kumpulan substring dalam deskripsi yang cocok dengan elemen dalam input pengguna. Hal ini berguna untuk menyoroti substring tersebut dalam aplikasi Anda. Dalam banyak kasus, kueri akan muncul sebagai substring kolom deskripsi.
    • length adalah panjang substring.
    • offset adalah offset karakter, yang diukur dari awal string deskripsi, tempat substring yang cocok muncul.
  • place_id adalah ID tekstual yang secara unik mengidentifikasi tempat. Untuk mengambil informasi tentang tempat, teruskan ID ini di kolom placeId pada permintaan Place Details. Pelajari lebih lanjut cara mereferensikan tempat dengan ID tempat.
  • terms adalah array yang berisi elemen kueri. Untuk sebuah tempat, setiap elemen biasanya akan membentuk sebagian alamat.
    • offset adalah offset karakter, yang diukur dari awal string deskripsi, tempat substring yang cocok muncul.
    • value adalah istilah yang cocok.

Contoh di bawah ini mengeksekusi permintaan prediksi kueri untuk frasa 'pizza di dekat' dan menampilkan hasilnya dalam daftar.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Coba Sampel

Lihat contoh

Token sesi

AutocompleteService.getPlacePredictions() menggunakan token sesi untuk mengelompokkan permintaan pelengkapan otomatis untuk tujuan penagihan. 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 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. Jika parameter sessionToken dihilangkan, atau jika Anda menggunakan kembali token sesi, sesi tersebut dikenai biaya seolah-olah tidak ada token sesi yang diberikan (setiap permintaan ditagih secara terpisah).

Anda dapat menggunakan token sesi yang sama untuk membuat satu permintaan Place Details di tempat yang dihasilkan dari panggilan ke AutocompleteService.getPlacePredictions(). Dalam hal ini, permintaan pelengkapan otomatis digabungkan dengan permintaan Place Details, dan panggilan dikenai biaya sebagai permintaan Place Details biasa. Permintaan pelengkapan otomatis tidak dikenai biaya.

Pastikan untuk meneruskan token sesi yang unik untuk setiap sesi baru. Penggunaan token yang sama untuk lebih dari satu sesi Autocomplete akan membatalkan sesi Autocomplete tersebut, dan semua permintaan Autocomplete dalam sesi yang tidak valid akan ditagih satu per satu menggunakan SKU Autocomplete Per Request. Baca selengkapnya tentang token sesi.

Contoh berikut menunjukkan pembuatan token sesi, lalu meneruskannya dalam AutocompleteService (fungsi displaySuggestions() telah dihilangkan agar lebih singkat):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Pastikan untuk meneruskan token sesi yang unik untuk setiap sesi baru. Jika menggunakan token yang sama untuk lebih dari satu sesi, setiap permintaan akan ditagih satu per satu.

Baca selengkapnya tentang token sesi.

Menata gaya widget Autocomplete dan SearchBox

Secara default, elemen UI yang disediakan oleh Autocomplete dan SearchBox ditata untuk disertakan dalam peta Google. Anda mungkin ingin menyesuaikan gaya visual agar cocok dengan situs Anda sendiri. Tersedia class CSS berikut. Semua class yang tercantum di bawah berlaku untuk widget Autocomplete dan SearchBox.

Ilustrasi grafis class CSS untuk widget Autocomplete dan SearchBox
Kelas CSS untuk widget Autocomplete dan SearchBox
Kelas CSS Deskripsi
pac-container Elemen visual yang berisi daftar prediksi yang ditampilkan oleh layanan Place Autocomplete. Daftar ini muncul sebagai daftar dropdown di bawah widget Autocomplete atau SearchBox.
pac-icon Ikon ditampilkan di sebelah kiri setiap item dalam daftar prediksi.
pac-item Item dalam daftar prediksi yang disediakan oleh widget Autocomplete atau SearchBox.
pac-item:hover Item saat pengguna menempatkan kursor mouse di atasnya.
pac-item-selected Item saat pengguna memilihnya melalui keyboard. Catatan: Item yang dipilih akan menjadi anggota class ini dan class pac-item.
pac-item-query Span di dalam pac-item yang merupakan bagian utama dari prediksi. Untuk lokasi geografis, kolom ini berisi nama tempat, seperti 'Sydney', atau nama dan nomor jalan, seperti '10 King Street'. Untuk penelusuran berbasis teks seperti 'pizza di New York', hasil ini berisi teks lengkap kueri. Secara default, pac-item-query berwarna hitam. Jika ada teks tambahan dalam pac-item, teks tersebut berada di luar pac-item-query dan mewarisi gayanya dari pac-item. Secara default, warnanya abu-abu. Teks tambahan biasanya berupa alamat.
pac-matched Bagian dari prediksi yang dikembalikan sesuai dengan masukan pengguna. Secara default, teks yang cocok ini ditandai dengan teks tebal. Perhatikan bahwa teks yang cocok dapat berada di mana saja dalam pac-item. Ini tidak harus merupakan bagian dari pac-item-query, dan dapat sebagian dalam pac-item-query serta sebagian dalam teks yang tersisa di pac-item.

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 adalah dengan menggunakan widget Autocomplete Maps JavaScript API, widget Autocomplete Places SDK for Android, atau kontrol UI Autocomplete Places SDK for iOS
  • Mengembangkan pemahaman tentang kolom data Place Autocomplete 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 melakukan degradasi halus jika API menampilkan error.
  • Pastikan aplikasi Anda menangani jika tidak ada pilihan dan tawarkan kepada pengguna cara 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 terprogram Place Autocomplete untuk mengakses Harga Per Permintaan dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details. Harga Per Permintaan yang disambungkan 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 kurang dari 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 prediksi yang dipilih?

Ya, memerlukan detail lebih lanjut

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 bawaan di dalam widget JavaScript, Android, atau iOS) dengan total biaya sebesar $0,017 per sesi ditambah SKU Data Tempat yang berlaku, bergantung pada kolom data tempat yang Anda minta.

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 perlu alamat dan lokasi

Geocoding API bisa 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 pengguna, tempat aplikasi digunakan, dan apakah praktik terbaik pengoptimalan performa telah diimplementasikan.

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 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 dari harga Per Session Autocomplete sebesar $0,017 per sesi.1

Pertimbangkan untuk menerapkan praktik terbaik performa untuk membantu pengguna Anda 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 harapkan sebelum pengguna memilih prediksi Place Autocomplete melebihi biaya Per Sesi, penerapan Place Autocomplete harus menggunakan token sesi untuk permintaan Place Autocomplete dan permintaan Place Details 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 Data Dasar.

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 Dasar 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 mengurangi permintaan. Misalnya, membuat permintaan Place Autocomplete untuk setiap karakter setelah pengguna mengetik karakter ketiga berarti bahwa jika pengguna mengetik tujuh karakter, lalu memilih prediksi tempat Anda membuat satu permintaan Geocoding API, total biayanya adalah $0.01632 (4 * $0.00283 Autocomplete Per Request + $0.005 Geocoding).1

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

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 Penagihan 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 mencondongkan 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 asli dalam panggilan ke Geocoding API.
    • Jika Anda memperkirakan pengguna memasukkan kueri untuk tempat tertentu berdasarkan nama atau alamat, gunakan permintaan Find Place. Jika hasil hanya diharapkan di region tertentu, gunakan pembiasan lokasi.
    Skenario lain jika sebaiknya melakukan fallback ke Geocoding API meliputi:
    • Pengguna yang memasukkan alamat subpremis di negara selain Australia, Selandia Baru, atau Kanada. Misalnya, alamat di AS "123 Bowdoin St #456, Boston MA, USA" tidak didukung oleh Autocomplete. (Pelengkapan otomatis 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, Selandia Baru" atau "145-112 Renfrew Dr, Markham, Ontario, Kanada".)
    • 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.

Kebijakan dan batas penggunaan

Kuota

Untuk informasi kuota dan harga, lihat dokumentasi Penggunaan dan Penagihan untuk Places API.

Kebijakan

Penggunaan Places Library, Maps JavaScript API harus sesuai dengan kebijakan yang dijelaskan untuk Places API.

Dari Persyaratan Layanan kami

Menampilkan logo
dan atribusi yang diperlukan

Hormati hak cipta dan atribusi Google. Pastikan logo dan pemberitahuan hak cipta terlihat, dan tampilkan "didukung oleh Google" logo jika Anda menggunakan data tanpa peta.

Pelajari Lebih Lanjut