Place Autocomplete

Pilih platform: Android iOS JavaScript Layanan Web

Places API generasi berikutnya kini tersedia dengan rilis class Place.

Catatan: Library sisi server

Halaman ini menjelaskan library sisi klien yang tersedia dengan Maps JavaScript API. Jika Anda ingin menggunakan layanan web Places API di server, lihat Klien Node.js untuk Layanan Google Maps. Halaman di link tersebut juga menyertakan Klien Java, Klien Python, dan Klien Go untuk Layanan Google Maps.

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.

  

  Gambar 1: Pelengkapan otomatis untuk kolom teks dan daftar pilihan

  

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

  

  Gambar 3: SearchBox menyajikan istilah penelusuran dan prediksi tempat.

  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.
    Catatan: Pembatasan lokasi hanya diterapkan ke seluruh rute, hasil sintetis yang terletak di luar pembatasan lokasi dapat ditampilkan berdasarkan rute yang tumpang-tindih dengan pembatasan lokasi.
  • 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.
    Catatan: Properti name akan berisi description dari prediksi Places Autocomplete. Anda dapat membaca description lebih lanjut di dokumentasi AutocompleteService.

    Pemberitahuan: placeIdOnly tidak digunakan lagi mulai 15 Januari 2019, dan akan dihentikan pada 15 Januari 2020. Gunakan array fields di antarmuka AutocompleteOptions sebagai gantinya: fields: ['place_id', 'name', 'types'].

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.

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

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

Catatan: Baca panduan tentang cara menggunakan TypeScript dan Google Maps.

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

Catatan: Jika Anda tidak memberikan batas atau area pandang peta, API akan berupaya mendeteksi lokasi pengguna dari alamat IP mereka, dan akan menampilkan hasil berdasarkan lokasi tersebut. Tetapkan batas jika memungkinkan. Jika tidak, pengguna lain mungkin akan menerima prediksi yang berbeda. Selain itu, guna meningkatkan ketepatan prediksi secara umum, penting untuk menyediakan area pandang yang logis seperti yang Anda tetapkan dengan menggeser atau melakukan zoom pada peta, atau area pandang yang ditetapkan developer berdasarkan lokasi dan radius perangkat. Jika radius tidak tersedia, 5 km akan dianggap sebagai nilai default yang wajar untuk Place Autocomplete. Jangan menetapkan area pandang dengan radius nol (satu titik), area pandang yang lebarnya hanya beberapa meter (kurang dari 100 m), atau area pandang yang membentang di globe.

Mengubah batas pada Autocomplete yang ada

Panggil setBounds() untuk mengubah area penelusuran pada Autocomplete yang ada menjadi 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);
index.ts

Catatan: Baca panduan tentang cara menggunakan TypeScript dan Google Maps.

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

Menetapkan batas ke area pandang peta

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

TypeScript

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

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

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

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

TypeScript

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

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

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.

TypeScript

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

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

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.

PENTING: Jangan gunakan Autocomplete untuk memperbarui ID Tempat karena setiap sesi akan dikenai biaya. Sebagai gantinya, panggil getDetails() dan hanya tentukan kolom place_id.

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.

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

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

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

Lihat contoh

Komponen alamat street_number mungkin tidak ada dalam respons Place Details untuk ID tempat dalam beberapa prediksi pelengkapan otomatis. Hal ini biasanya terjadi jika alamat tidak dapat diinterpolasi untuk suatu tempat. Dalam hal ini, array types prediksi akan berisi "route". Untuk prediksi pelengkapan otomatis dengan angka dalam deskripsi (kueri input cocok), respons Place Details untuk ID tempat akan berisi nomor jalan hanya jika array types untuk prediksi berisi setidaknya salah satu dari:

• street_address
• premise
• establishment

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

Secara default, saat pengguna memilih tempat, SearchBox mengembalikan semua kolom data yang tersedia untuk tempat yang dipilih, dan Anda akan ditagih sesuai dengan jumlah tersebut. Tidak ada cara untuk membatasi permintaan SearchBox untuk hanya menampilkan kolom tertentu. Agar tidak meminta (dan membayar) data yang tidak Anda perlukan, gunakan widget Autocomplete.

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.

Catatan: Saat Anda menampilkan prediksi dari kotak penelusuran Google Places, Anda harus menyertakan logo 'dengan teknologi Google'. Logo ini disertakan pada daftar hasil secara default, untuk kenyamanan 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.

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

Catatan: Baca panduan tentang cara menggunakan TypeScript dan Google Maps.

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

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

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

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

Catatan: JavaScript dikompilasi dari cuplikan TypeScript.

CSS

style.css

HTML

<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

Mencoba Contoh

JSFiddle.net Google Cloud Shell

Lihat contoh

Token sesi

Tips: Jika aplikasi Anda menggunakan Widget Autocomplete, Anda tidak perlu menerapkan sesi, karena widget menangani sesi secara otomatis di latar belakang.

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.

Class CSS untuk widget Autocomplete dan SearchBox

Class CSS	Deskripsi
pac-container	Elemen visual berisi daftar prediksi yang ditampilkan oleh layanan Place Autocomplete. Daftar ini muncul sebagai daftar dropdown di bawah widget Autocomplete atau SearchBox.
pac-icon	Ikon yang 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, isinya adalah nama tempat, seperti 'Sydney', atau nama jalan dan nomor rumah, seperti '10 King Street'. Untuk penelusuran berbasis teks seperti 'pizza in New York', isinya adalah teks lengkap dari kueri. Secara default, pac-item-query warnanya 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 ditampilkan sesuai dengan input pengguna. Secara default, teks yang cocok ini disorot dalam teks tebal. Perhatikan bahwa teks yang cocok dapat berada di mana saja dalam pac-item. Class ini belum tentu bagian dari pac-item-query, dan bisa saja sebagian dalam pac-item-query serta sebagian lagi dalam teks sisanya 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 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.

Untuk mendapatkan bantuan dalam memilih penerapan Place Autocomplete yang sesuai dengan kebutuhan Anda, pilih tab yang sesuai dengan jawaban Anda untuk pertanyaan berikut.

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

Ya, memerlukan informasi lebih detail

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

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

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

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

Tidak, hanya memerlukan alamat dan lokasi

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

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

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

Ya

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

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

Tidak

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

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

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

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

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

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

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

---

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

Praktik terbaik performa

Panduan berikut menjelaskan cara mengoptimalkan performa Place Autocomplete:

• Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Place Autocomplete Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
• Jika Place Autocomplete disertai 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.

Petunjuk: Anda dapat menggunakan Place Autocomplete meskipun tanpa peta. Jika Anda menampilkan peta, maka harus peta Google.