Bermigrasi ke Place Autocomplete baru

Developer Wilayah Ekonomi Eropa (EEA)

Jika alamat penagihan Anda berada di Wilayah Ekonomi Eropa, mulai 8 Juli 2025, Persyaratan Layanan Google Maps Platform EEA akan berlaku untuk penggunaan Layanan oleh Anda. Fungsi bervariasi menurut wilayah. Pelajari lebih lanjut.

Place Autocomplete adalah fitur Places Library di Maps JavaScript API. Anda dapat menggunakan pelengkapan otomatis untuk memberi aplikasi Anda perilaku prediksi penelusuran di kolom penelusuran Google Maps.

Halaman ini menjelaskan perbedaan antara fitur Place Autocomplete lama dan baru. Di kedua versi, ada dua cara umum untuk mengintegrasikan Pelengkapan Otomatis:

• Antarmuka terprogram: Untuk developer yang menginginkan penyesuaian dan kontrol yang lebih besar atas pengalaman pelengkapan otomatis.
• Widget Place Autocomplete: Kotak penelusuran yang dapat disematkan di peta atau halaman web.

Antarmuka terprogram pelengkapan otomatis

Tabel berikut mencantumkan beberapa perbedaan utama dalam penggunaan Place Autocomplete terprogram antara Layanan Place Autocomplete (lama) dan Autocomplete Data API (baru):

PlacesService (Lama)	Place (Baru)
Referensi Places Autocomplete Service	Referensi Data Pelengkapan Otomatis (baru)
AutocompletionRequest	AutocompleteRequest
AutocompleteService.getPlacePredictions	AutocompleteSuggestion.fetchAutocompleteSuggestions
AutocompletePrediction	PlacePrediction
Metode memerlukan penggunaan callback untuk menangani objek hasil dan respons PlacesServiceStatus.	Menggunakan Promise, dan berfungsi secara asinkron.
Metode memerlukan pemeriksaan PlacesServiceStatus.	Tidak ada pemeriksaan status yang diperlukan, dapat menggunakan penanganan error standar. Pelajari lebih lanjut.
Kolom data tempat ditetapkan sebagai opsi saat instance Autocomplete dibuat.	Kolom data tempat ditetapkan nanti saat fetchFields() dipanggil.
Prediksi kueri didukung (khusus SearchBox).	Prediksi kueri tidak tersedia di class Autocomplete.
Terbatas pada kumpulan tetap jenis tempat dan kolom data tempat.	Akses ke pilihan jenis tempat yang lebih luas dan kolom data tempat.

Berikut ini digunakan oleh Autocomplete API lama dan baru:

• locationBias
• locationRestriction
• AutocompleteSessionToken
• ComponentRestrictions

Perbandingan kode (terprogram)

Bagian ini membandingkan kode untuk pelengkapan otomatis guna menggambarkan perbedaan antara Places Service dan class Place, untuk antarmuka terprogram.

Mengambil prediksi pelengkapan otomatis (lama)

Places Service lama memungkinkan Anda mengambil prediksi pelengkapan otomatis secara terprogram, untuk kontrol yang lebih besar atas antarmuka pengguna daripada yang ditawarkan oleh class Autocomplete. Dalam contoh berikut, satu permintaan dibuat untuk "par", dengan AutocompletionRequest yang terdiri dari nilai input dan serangkaian batas untuk memengaruhi prediksi. Contoh menampilkan daftar instance AutocompletePrediction, dan menampilkan deskripsi untuk setiap instance. Fungsi contoh juga membuat token sesi dan menerapkannya ke permintaan.

function init() {
  const placeInfo = document.getElementById("prediction");
  const service = new google.maps.places.AutocompleteService();
  const placesService = new google.maps.places.PlacesService(placeInfo);
  var sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    bounds: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  }

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const displaySuggestions = function (predictions, status) {
    // Check the status of the Places Service.
    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 placeRequest = {
      placeId: predictions[0].place_id,
      fields: ["name", "formatted_address"],
    };

    placesService.getDetails(placeRequest, (place, status) => {
      if (status == google.maps.places.PlacesServiceStatus.OK && place) {
        placeInfo.textContent = `
          First predicted place: ${place.name} at ${place.formatted_address}`
      }
    });

  };

  // Show the results of the query.
  service.getPlacePredictions(request, displaySuggestions);
}

• Mengambil prediksi Layanan Place Autocomplete secara terprogram
• Contoh Place Autocomplete
• Token sesi
• AutocompletionRequest referensi
• AutocompletePrediction referensi

Mengambil prediksi pelengkapan otomatis (baru)

Class Place baru juga memungkinkan Anda mengambil prediksi pelengkapan otomatis secara terprogram untuk mendapatkan kontrol yang lebih besar atas antarmuka pengguna daripada yang ditawarkan oleh class PlaceAutocompleteElement. Dalam contoh berikut, satu permintaan dibuat untuk "par", dengan AutocompleteRequest yang terdiri dari nilai input dan serangkaian batas untuk membuat prediksi yang bias. Contoh ini menampilkan daftar instance placePrediction dan menampilkan deskripsi untuk setiap instance. Fungsi contoh juga membuat token sesi dan menerapkannya ke permintaan.

async function init() {
  let sessionToken = new google.maps.places.AutocompleteSessionToken();

  // Define request options.
  let request = {
    input: "par",
    sessionToken: sessionToken,
    locationBias: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
  };

  // Display the query string.
  const title = document.getElementById("title");
  title.appendChild(
    document.createTextNode('Place predictions for "' + request.input + '":'),
  );

  // Perform the query and display the results.
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

  const resultsElement = document.getElementById("results");

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    const listItem = document.createElement("li");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.text),
    );

    resultsElement.appendChild(listItem);
  }

  // Show the first predicted place.
  let place = suggestions[0].placePrediction.toPlace();

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent = `
    First predicted place: ${place.displayName} at ${place.formattedAddress}`
}

• Place Autocomplete Data API
• Contoh Prediksi Data Place Autocomplete
• Contoh Sesi Data Place Autocomplete
• Token sesi
• Referensi antarmuka AutocompleteRequest
• Referensi class AutocompleteSuggestion
• Referensi class PlacePrediction

Widget pelengkapan otomatis tempat

Tabel berikut mencantumkan beberapa perbedaan utama dalam penggunaan widget pelengkapan otomatis antara layanan Places (lama), dan class Place (baru):

Layanan Places (Lama)	Tempat (Baru)
Class Autocomplete untuk prediksi tempat.	Class PlaceAutocompleteElement untuk prediksi tempat.
Class SearchBox untuk prediksi kueri.	Prediksi kueri tidak tersedia di class Autocomplete.
Hanya teks placeholder input default yang dilokalkan.	Placeholder input teks, logo daftar prediksi, dan prediksi tempat semuanya mendukung pelokalan regional.
Widget menggunakan setBounds() atau autocomplete.bindTo() untuk membatasi (membuat bias) penelusuran ke batas yang ditentukan, dan strictBounds untuk membatasi hasil ke batas yang ditentukan.	Widget menggunakan properti locationBias untuk membiaskan hasil ke batas yang ditentukan, dan properti locationRestriction untuk membatasi penelusuran ke batas yang ditentukan.
Widget hanya dapat diintegrasikan dengan menggunakan elemen input HTML standar.	Widget dapat diintegrasikan menggunakan elemen input HTML standar atau elemen gmp-place-autocomplete.
Saat menggunakan widget, pengguna dapat meminta hal-hal yang mungkin tidak valid (misalnya "bisneyland"); kasus ini harus ditangani secara eksplisit.	Widget hanya akan menampilkan hasil untuk saran yang diberikan, dan tidak dapat mengeluarkan permintaan untuk nilai arbitrer; oleh karena itu, tidak perlu menangani permintaan yang berpotensi tidak valid.
Menampilkan instance PlaceResult lama.	Menampilkan instance Place.
Kolom data tempat ditetapkan sebagai opsi untuk objek Autocomplete.	Kolom data tempat ditetapkan saat pengguna membuat pilihan dan fetchFields() dipanggil.
Terbatas pada kumpulan tetap jenis tempat dan kolom data tempat.	Akses ke pilihan jenis tempat yang lebih luas dan kolom data tempat.

Perbandingan kode (widget)

Bagian ini membandingkan kode untuk pelengkapan otomatis guna menggambarkan perbedaan antara Widget Place Autocomplete lama dan elemen Place Autocomplete baru.

Widget Place Autocomplete (lama)

Layanan Places menawarkan dua jenis widget pelengkapan otomatis, yang dapat Anda tambahkan menggunakan class Autocomplete dan SearchBox. Setiap jenis widget dapat ditambahkan ke peta sebagai kontrol peta, atau disematkan langsung ke halaman web. Contoh kode berikut menunjukkan cara menyematkan widget Autocomplete sebagai kontrol peta.

• Konstruktor widget 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, tempat Anda dapat menentukan opsi lebih lanjut untuk membatasi kueri.
• Untuk menetapkan batas, instance Autocomplete dapat terikat secara eksplisit ke peta dengan memanggil autocomplete.bindTo().
• Tentukan kolom data tempat dalam opsi untuk pelengkapan otomatis.

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapTypeControl: false,
  });
  const card = document.getElementById("pac-card");
  const input = document.getElementById("pac-input");
  const options = {
    fields: ["formatted_address", "geometry", "name"],
    strictBounds: false,
  };

  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

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

  // Bind the map's bounds (viewport) property to the autocomplete object,
  // so that the autocomplete requests use the current map bounds for the
  // bounds option in the request.
  autocomplete.bindTo("bounds", map);

  const infowindow = new google.maps.InfoWindow();
  const infowindowContent = document.getElementById("infowindow-content");

  infowindow.setContent(infowindowContent);

  const marker = new google.maps.Marker({
    map,
    anchorPoint: new google.maps.Point(0, -29),
  });

  autocomplete.addListener("place_changed", () => {
    infowindow.close();
    marker.setVisible(false);

    const place = autocomplete.getPlace();

    if (!place.geometry || !place.geometry.location) {
      // User entered the name of a Place that was not suggested and
      // pressed the Enter key, or the Place Details request failed.
      window.alert("No details available for input: '" + place.name + "'");
      return;
    }

    // If the place has a geometry, then present it on a map.
    if (place.geometry.viewport) {
      map.fitBounds(place.geometry.viewport);
    } else {
      map.setCenter(place.geometry.location);
      map.setZoom(17);
    }

    marker.setPosition(place.geometry.location);
    marker.setVisible(true);
    infowindowContent.children["place-name"].textContent = place.name;
    infowindowContent.children["place-address"].textContent =
      place.formatted_address;
    infowindow.open(map, marker);
  });
}

• Dokumentasi Place Autocomplete
• Contoh Widget Place Autocomplete
• Contoh Kotak Penelusuran Places
• Referensi class Autocomplete

Widget Place Autocomplete (Baru)

Class Place menawarkan PlaceAutocompleteElement, subclass HTMLElement yang menyediakan komponen UI yang dapat ditambahkan ke peta sebagai kontrol peta, atau disematkan langsung ke halaman web. Contoh kode berikut menunjukkan cara menyematkan widget PlaceAutocompleteElement sebagai kontrol peta.

Widget Place Autocomplete telah ditingkatkan dengan cara berikut:

• UI widget Autocomplete mendukung pelokalan regional (termasuk bahasa RTL), untuk placeholder input teks, logo daftar prediksi, dan prediksi tempat.
• Aksesibilitas yang ditingkatkan, termasuk dukungan untuk pembaca layar dan interaksi keyboard.
• Widget Autocomplete menampilkan class Place baru untuk menyederhanakan penanganan objek yang ditampilkan.
• Dukungan yang lebih baik untuk perangkat seluler dan layar kecil.
• Performa dan tampilan grafis yang lebih baik.

Perbedaan utama penerapan meliputi:

• PlaceAutocompleteElement menyediakan kolom inputnya sendiri, dan dimasukkan langsung ke halaman menggunakan HTML atau JavaScript (bukan menyediakan elemen input yang ada).
• Prediksi kueri tidak tersedia di class Autocomplete.
• PlaceAutocompleteElement dibuat menggunakan PlaceAutocompleteElementOptions.
  • Kolom data tempat ditentukan pada waktu pemilihan (saat fetchFields() dipanggil).
• Tetapkan batas menggunakan opsi locationBounds atau locationRestriction.

let map;
let marker;
let infoWindow;

async function initMap() {
  // Request needed libraries.
  const [{ Map }, { AdvancedMarkerElement }] = await Promise.all([
    google.maps.importLibrary("marker"),
    google.maps.importLibrary("places"),
  ]);

  // Initialize the map.
  map = new google.maps.Map(document.getElementById("map"), {
    center: { lat: 40.749933, lng: -73.98633 },
    zoom: 13,
    mapId: "4504f8b37365c3d0",
    mapTypeControl: false,
  });

  const placeAutocomplete =
    new google.maps.places.PlaceAutocompleteElement({
      locationRestriction: map.getBounds(),
    });

  placeAutocomplete.id = "place-autocomplete-input";
  const card = document.getElementById("place-autocomplete-card");

  card.appendChild(placeAutocomplete);
  map.controls[google.maps.ControlPosition.TOP_LEFT].push(card);

  // Create the marker and infowindow.
  marker = new google.maps.marker.AdvancedMarkerElement({
    map,
  });
  infoWindow = new google.maps.InfoWindow({});

  // Add the gmp-select listener, and display the results on the map.
  placeAutocomplete.addEventListener("gmp-select", async ( place ) => {
    const place = event.placePrediction.toPlace();
    await place.fetchFields({
      fields: ["displayName", "formattedAddress", "location"],
    });
    // If the place has a geometry, then present it on a map.
    if (place.viewport) {
      map.fitBounds(place.viewport);
    } else {
      map.setCenter(place.location);
      map.setZoom(17);
    }

    let content =
      '<div id="infowindow-content">' +
      '<span id="place-displayname" class="title">' +
      place.displayName +
      '</span><br />' +
      '<span id="place-address">' +
      place.formattedAddress +
      '</span>' +
      '</div>';

    updateInfoWindow(content, place.location);
    marker.position = place.location;
  });
}

// Helper function to create an info window.
function updateInfoWindow(content, center) {
  infoWindow.setContent(content);
  infoWindow.setPosition(center);
  infoWindow.open({
    map,
    anchor: marker,
    shouldFocus: false,
  });
}

• Dokumentasi Widget Place Autocomplete (Pratinjau)
• Contoh widget Place Autocomplete
• Contoh Elemen Place Autocomplete
• Referensi class PlaceAutocompleteElement