Place Autocomplete

Pengantar

Autocomplete adalah fitur Places Library di Maps JavaScript API. Anda dapat menggunakan Autocomplete untuk memberi aplikasi Anda perilaku prediksi penelusuran di kolom penelusuran Google Maps. Layanan Autocomplete dapat mencocokkan kata dan substring lengkap, yang me-resolve nama tempat, alamat, dan Plus Codes. Karena itu aplikasi dapat mengirimkan kueri saat pengguna mengetik, untuk memberikan prediksi tempat secara real time. Seperti yang ditentukan oleh Places API, 'tempat' dapat berupa tempat usaha, lokasi geografis, atau lokasi menarik terkemuka.

Memulai

Sebelum menggunakan Places Library di Maps JavaScript API, pastikan terlebih dahulu Places API diaktifkan di Konsol Google Cloud, dalam project yang sama 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 Dashboard, cari Places API.
4. Jika sudah melihat API di dalam daftar, artinya Anda sudah siap. Jika API tidak tercantum, aktifkan API tersebut:
   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 ENABLE. Setelah proses ini selesai, Places API akan muncul dalam daftar API di Dashboard.

Memuat library

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

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

Lihat Ringkasan Library untuk informasi selengkapnya.

Ringkasan class

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).

Berikut rangkuman class yang tersedia:

• Autocomplete menambahkan kolom input teks ke halaman web Anda, dan memantau pengisian karakter pada kolom tersebut. Saat pengguna memasukkan teks, pelengkapan otomatis akan menampilkan prediksi tempat dalam bentuk daftar pilihan dropdown. Jika pengguna memilih tempat dari daftar tersebut, informasi tentang tempat akan ditampilkan ke objek pelengkapan otomatis, dan dapat diambil oleh aplikasi Anda. Lihat detailnya di bawah.

  

  

• SearchBox menambahkan kolom input teks ke halaman web Anda, dengan cara yang sama seperti Autocomplete. Perbedaannya adalah sebagai berikut:
  • Perbedaan utama ada 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 in new', daftar pilihan mungkin menyertakan frasa 'pizza in New York, NY' serta nama-nama berbagai gerai pizza.
  • SearchBox menawarkan lebih sedikit opsi daripada Autocomplete untuk membatasi penelusuran. Pada yang pertama, Anda dapat mengarahkan penelusuran ke LatLngBounds yang diberikan. Pada yang berikutnya, Anda bisa membatasi penelusuran ke negara tertentu dan jenis tempat tertentu, serta menetapkan batasnya. Untuk informasi selengkapnya, lihat di bawah.

  

  Lihat detailnya di bawah.
• Anda dapat membuat objek AutocompleteService untuk mengambil prediksi secara terprogram. Panggil getPlacePredictions() untuk mengambil tempat yang cocok, atau panggil getQueryPredictions() untuk mengambil tempat yang cocok beserta istilah penelusuran yang disarankan. Catatan: AutocompleteService tidak menambahkan kontrol UI apa pun. Sebagai gantinya, metode di atas menampilkan array objek prediksi. Setiap objek prediksi berisi teks prediksi, serta informasi referensi dan detail tentang cara menyesuaikan hasilnya dengan masukan 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 pilihan menunjukkan satu tempat (seperti yang ditentukan oleh Places API).

Konstruktor Autocomplete menggunakan dua argumen:

• Elemen input HTML dari jenis text. Ini adalah kolom input yang akan dipantau oleh layanan pelengkapan otomatis dan untuk 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 (hal 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 dibiaskan terhadap, 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 wilayah yang ditentukan oleh bounds yang diberikan. API tidak menampilkan hasil di luar wilayah 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 berupa dua karakter kode negara yang kompatibel dengan ISO 3166-1 Alpha-2. Beberapa negara harus diteruskan sebagai daftar kode negara.

    Catatan: Jika Anda menerima hasil yang tidak terduga dengan kode negara, pastikan Anda menggunakan kode yang mencakup negara, wilayah dependen, dan area minat geografis khusus yang Anda inginkan. Anda dapat menemukan informasi kode di Wikipedia: List of ISO 3166 country codes (Wikipedia: Daftar kode negara ISO 3166) atau ISO Online Browsing Platform (Platform Penjelajahan Online ISO).

  • placeIdOnly dapat digunakan untuk memerintahkan widget Autocomplete agar hanya mengambil ID Tempat. Saat memanggil getPlace() pada objek Autocomplete, PlaceResult yang disediakan 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, dengan kecenderungan prediksi di dekat lokasi pengguna, dan mengambil semua kolom data yang tersedia untuk tempat yang dipilih pengguna. Tetapkan opsi Place Autocomplete untuk memberikan prediksi yang lebih relevan berdasarkan kasus penggunaan Anda.

Menetapkan opsi saat pembuatan

Konstruktor Autocomplete menerima parameter AutocompleteOptions untuk menetapkan batasan saat pembuatan widget. Contoh berikut menetapkan opsi bounds, componentRestrictions, dan types untuk meminta tempat jenis establishment, yang memprioritaskan tempat dalam area geografis yang ditentukan dan membatasi prediksi hanya ke 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.

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,
};

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

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,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
index.js

Menentukan kolom data

Tentukan kolom data agar tidak ditagih untuk SKU Data Places yang tidak Anda perlukan. 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 membiaskan hasil pelengkapan otomatis untuk mendukung suatu perkiraan lokasi atau area, dengan cara berikut:

• Menetapkan batas saat pembuatan objek Autocomplete.
• Mengubah batas Autocomplete yang sudah ada.
• Menetapkan 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 pada Autocomplete yang ada

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

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);
index.ts

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);
index.js

Menetapkan batas ke area pandang peta

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

autocomplete.bindTo("bounds", map);
index.ts

autocomplete.bindTo("bounds", map);
index.js

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

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

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

Lihat contoh

Membatasi penelusuran ke batas saat ini

Tetapkan opsi strictBounds untuk membatasi hasil ke 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 ke kumpulan spesifik yang berisi hingga lima negara.

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

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

Lihat contoh

Membatasi jenis tempat

Gunakan opsi types atau panggil setTypes() untuk membatasi prediksi ke jenis tempat tertentu. Batasan ini menentukan jenis atau kumpulan jenis, seperti yang tercantum dalam Jenis Tempat. 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 atauTabel 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.

Lihat demo

Mendapatkan informasi tempat

Saat pengguna memilih tempat dari prediksi yang disertakan 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 lebih banyak informasi tentang tempat yang dipilih.

Secara default, saat pengguna memilih suatu tempat, pelengkapan otomatis menampilkan semua kolom data yang tersedia untuk tempat yang dipilih, dan Anda akan ditagih sebagaimana mestinya. Gunakan Autocomplete.setFields() untuk menentukan kolom data tempat yang akan dikembalikan. 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.

Formulir alamat perlu mendapatkan alamat dalam format terstruktur. Untuk mengembalikan alamat terstruktur untuk tempat yang dipilih, panggil Autocomplete.setFields() dan tentukan kolom address_components.

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

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();
}
index.ts

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;
index.js

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 menetapkan 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 tentang pelokalan.

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

Menambahkan widget SearchBox

Dengan SearchBox, pengguna dapat melakukan penelusuran geografis berbasis teks, seperti 'pizza in New York' atau 'shoe stores near robson street'. Anda dapat melampirkan SearchBox ke kolom teks, dan saat teks dimasukkan, layanan ini 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 in new', daftar pilihan mungkin menyertakan frasa 'pizza in New York, NY' serta nama-nama berbagai gerai pizza. Jika pengguna memilih tempat dari daftar tersebut, informasi tentang tempat akan ditampilkan ke objek SearchBox, dan dapat diambil oleh aplikasi Anda.

Konstruktor SearchBox menggunakan dua argumen:

• Elemen input HTML dari jenis text. Ini adalah kolom input yang akan dipantau oleh layanan SearchBox dan untuk 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 bounds untuk mencondongkan hasil ke tempat yang ada dalam area geografis tertentu, yang ditetapkan melalui koordinat garis lintang/garis 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.

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

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

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, class ini menampilkan array objek prediksi, yang masing-masing berisi teks prediksi, informasi referensi, dan detail tentang kecocokan hasil dengan input pengguna. Hal ini berguna jika Anda menginginkan lebih banyak kontrol terhadap antarmuka pengguna daripada yang ditawarkan oleh Autocomplete dan SearchBox yang dijelaskan di atas.

AutocompleteService mengekspos metode berikut:

• getPlacePredictions() menampilkan prediksi tempat. Catatan: Sebuah 'tempat' dapat berupa tempat usaha, lokasi geografis, atau lokasi menarik terkemuka, sebagaimana didefinisikan oleh Places API.
• getQueryPredictions() menampilkan daftar prediksi tambahan, yang dapat mencakup tempat (seperti yang ditentukan oleh Places API) dan istilah penelusuran yang disarankan. Misalnya, jika pengguna memasukkan 'pizza in new', daftar pilihan mungkin menyertakan frasa 'pizza in New York, NY' serta nama-nama berbagai gerai pizza.

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

• description adalah prediksi yang cocok.
• distance_meters adalah jarak tempat dalam meter 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 dalam 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 membentuk bagian 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 near' dan menampilkan hasilnya dalam daftar.

// 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;
index.ts

// 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;
index.js

style.css

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>

    <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 script 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. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Lihat contoh

Token sesi

AutocompleteService.getPlacePredictions() dapat menggunakan token sesi (jika diterapkan) 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, 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. 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 Autocomplete 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 telah ditata untuk dimasukkan dalam peta Google. Anda mungkin perlu menyesuaikan gaya dengan situs Anda sendiri. Tersedia class CSS berikut. Semua class yang tercantum di bawah berlaku untuk widget Autocomplete dan SearchBox.

Pengoptimalan Place Autocomplete

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

Berikut ini beberapa pedoman umum:

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

Praktik terbaik pengoptimalan biaya

Pengoptimalan biaya dasar

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

Pengoptimalan biaya lanjutan

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

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

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

Praktik terbaik performa

Panduan berikut menjelaskan cara mengoptimalkan performa Place Autocomplete:

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

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.