Data API Place Autocomplete

Place Autocomplete Data API memungkinkan Anda mengambil prediksi tempat secara terprogram, untuk menciptakan pengalaman pelengkapan otomatis yang disesuaikan dengan tingkat kontrol yang lebih baik daripada yang dapat dilakukan dengan widget pelengkapan otomatis. Dalam panduan ini, Anda akan mempelajari cara menggunakan Data API Place Autocomplete untuk membuat permintaan pelengkapan otomatis berdasarkan kueri pengguna.

Contoh berikut menunjukkan integrasi prediksi pengetikan yang sederhana. Masukkan kueri penelusuran, lalu klik untuk memilih hasil yang Anda inginkan.

Catatan: Anda dapat menggunakan Place Autocomplete Data API meskipun tanpa peta. Jika Anda menampilkan peta, maka harus peta Google. Jika Anda menampilkan prediksi dari layanan pelengkapan otomatis tanpa peta, Anda harus menyertakan logo Google yang ditampilkan inline dengan kolom/hasil penelusuran. Untuk informasi selengkapnya, lihat Menampilkan logo dan atribusi Google.

Permintaan Pelengkapan Otomatis

Permintaan Autocomplete mengambil string input kueri dan menampilkan daftar prediksi tempat. Untuk membuat permintaan pelengkapan otomatis, panggil fetchAutocompleteSuggestions() dan teruskan permintaan dengan properti yang diperlukan. Properti input berisi string yang akan ditelusuri; dalam aplikasi biasa, nilai ini akan diperbarui saat pengguna mengetik kueri. Permintaan harus menyertakan sessionToken, yang digunakan untuk tujuan penagihan.

Cuplikan berikut menunjukkan pembuatan isi permintaan dan penambahan token sesi, lalu memanggil fetchAutocompleteSuggestions() untuk mendapatkan daftar PlacePrediction.

// Add an initial request body.
let request = {
  input: "Tadi",
  locationRestriction: {
    west: -122.44,
    north: 37.8,
    east: -122.39,
    south: 37.78,
  },
  origin: { lat: 37.7893, lng: -122.4039 },
  includedPrimaryTypes: ["restaurant"],
  language: "en-US",
  region: "us",
};
// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;
index.js

Membatasi prediksi Autocomplete

Secara default, Place Autocomplete menampilkan semua jenis tempat, dengan bias prediksi di dekat lokasi pengguna, lalu mengambil semua kolom data yang tersedia untuk tempat yang dipilih pengguna. Tetapkan opsi Place Autocomplete untuk memberikan prediksi yang lebih relevan, dengan membatasi atau membiaskan hasil.

Membatasi hasil akan menyebabkan widget Autocomplete mengabaikan hasil apa pun yang berada di luar area pembatasan. Praktik yang umum adalah membatasi hasil ke batas peta. Membiaskan hasil akan membuat widget Autocomplete menampilkan hasil dalam area yang ditentukan, tetapi beberapa hasil yang cocok mungkin berada di luar area tersebut.

Gunakan properti origin untuk menentukan titik asal untuk menghitung jarak geodesi ke tujuan. Jika nilai ini dihilangkan, jarak tidak ditampilkan.

Gunakan properti includedPrimaryTypes untuk menentukan hingga lima jenis tempat. Jika tidak ada jenis yang ditentukan, semua jenis tempat akan ditampilkan.

Lihat referensi API

Mendapatkan detail tempat

Untuk menampilkan objek Place dari hasil prediksi tempat, panggil toPlace() terlebih dahulu, lalu panggil fetchFields() pada objek Place yang dihasilkan (ID sesi dari prediksi tempat otomatis disertakan). Memanggil fetchFields() akan mengakhiri sesi pelengkapan otomatis.

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

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

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

placeInfo.textContent =
  "First predicted place: " +
  place.displayName +
  ": " +
  place.formattedAddress;
index.js

Token sesi

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. Sesi akan diakhiri saat pengguna memilih tempat dan panggilan ke Place Details dilakukan.

Untuk membuat token sesi baru dan menambahkannya ke permintaan, buat instance AutocompleteSessionToken, lalu tetapkan properti sessionToken permintaan untuk menggunakan token tersebut seperti yang ditunjukkan dalam cuplikan berikut:

// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;
index.js

Sesi diakhiri saat fetchFields() dipanggil. Setelah membuat instance Place, Anda tidak perlu meneruskan token sesi ke fetchFields() karena token ini akan ditangani secara otomatis.

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

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

Buat token sesi untuk sesi berikutnya dengan membuat instance AutocompleteSessionToken baru.

Rekomendasi token sesi:

• Gunakan token sesi untuk semua panggilan Place Autocomplete.
• Buat token baru untuk setiap sesi.
• Teruskan token sesi unik untuk setiap sesi baru. Jika token yang sama digunakan untuk lebih dari satu sesi, setiap permintaan akan ditagih satu per satu.

Anda dapat memilih untuk menghilangkan token sesi pelengkapan otomatis dari permintaan. Jika token sesi dihilangkan, setiap permintaan akan ditagih secara terpisah, sehingga memicu SKU Autocomplete - Per Request. Jika token sesi digunakan ulang, sesi tersebut dianggap tidak valid dan permintaan akan dikenai biaya seolah-olah tidak ada token sesi yang diberikan.

Contoh

Saat pengguna mengetik kueri, permintaan pelengkapan otomatis akan dipanggil setiap beberapa penekanan tombol (bukan per karakter), dan daftar kemungkinan hasil akan ditampilkan. Saat pengguna membuat pilihan dari daftar hasil, pilihan tersebut akan dihitung sebagai permintaan, dan semua permintaan yang dibuat selama penelusuran akan digabungkan dan dihitung sebagai satu permintaan. Jika pengguna memilih tempat, kueri penelusuran tersedia gratis, dan hanya permintaan data Tempat yang dikenai biaya. Jika pengguna tidak menentukan pilihan dalam beberapa menit di awal sesi, hanya kueri penelusuran yang akan dikenai biaya.

Dari perspektif aplikasi, alur peristiwa berjalan seperti ini:

1. Pengguna mulai mengetik kueri untuk menelusuri "Paris, Prancis".
2. Setelah mendeteksi input pengguna, aplikasi akan membuat token sesi baru, "Token A".
3. Saat pengguna mengetik, API akan membuat permintaan pelengkapan otomatis setiap beberapa karakter, yang menampilkan daftar baru hasil potensial untuk setiap karakter:
   "P"
   "Par"
   "Paris,"
   "Paris, Fr"
   
4. Saat pengguna membuat pilihan:
   • Semua permintaan yang dihasilkan dari kueri dikelompokkan dan ditambahkan ke sesi yang direpresentasikan oleh "Token A", sebagai permintaan tunggal.
   • Pilihan pengguna dihitung sebagai permintaan Place Detail, dan ditambahkan ke sesi yang direpresentasikan oleh "Token A".
5. Sesi berakhir, dan aplikasi akan menghapus "Token A".

Pelajari cara penagihan sesi

Kode contoh lengkap

Bagian ini berisi contoh lengkap yang menunjukkan cara menggunakan Place Autocomplete Data API .

Prediksi Place Autocomplete

Contoh berikut menunjukkan pemanggilan fetchAutocompleteSuggestions() untuk input "Tadi", lalu memanggil toPlace() pada hasil prediksi pertama, diikuti dengan panggilan ke fetchFields() untuk mendapatkan detail tempat.

TypeScript

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
    // @ts-ignore
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary("places") as google.maps.PlacesLibrary;

    // Add an initial request body.
    let request = {
        input: "Tadi",
        locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ["restaurant"],
        language: "en-US",
        region: "us",
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title') as HTMLElement;
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));

    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');
        const resultsElement = document.getElementById("results") as HTMLElement;
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }

    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById("prediction") as HTMLElement;
    placeInfo.textContent = 'First predicted place: ' + place.displayName + ': ' + place.formattedAddress;

}

init();
index.ts

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
  // @ts-ignore
  const { Place, AutocompleteSessionToken, AutocompleteSuggestion } =
    await google.maps.importLibrary("places");
  // Add an initial request body.
  let request = {
    input: "Tadi",
    locationRestriction: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ["restaurant"],
    language: "en-US",
    region: "us",
  };
  // Create a session token.
  const token = new AutocompleteSessionToken();

  // Add the token to the request.
  // @ts-ignore
  request.sessionToken = token;

  // Fetch autocomplete suggestions.
  const { suggestions } =
    await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
  const title = document.getElementById("title");

  title.appendChild(
    document.createTextNode('Query predictions for "' + request.input + '":'),
  );

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a new list element.
    const listItem = document.createElement("li");
    const resultsElement = document.getElementById("results");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.toString()),
    );
    resultsElement.appendChild(listItem);
  }

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

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

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

  placeInfo.textContent =
    "First predicted place: " +
    place.displayName +
    ": " +
    place.formattedAddress;
}

init();
index.js

Catatan: JavaScript dikompilasi dari cuplikan TypeScript.

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}
style.css

HTML

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

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="title"></div>
    <ul id="results"></ul>
    <p><span id="prediction"></span></p>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

Mencoba Contoh

JSFiddle.net Google Cloud Shell

Menempatkan pelengkapan otomatis saat mengetik dengan sesi

Contoh ini menunjukkan pemanggilan fetchAutocompleteSuggestions() berdasarkan kueri pengguna, yang menampilkan daftar prediksi tempat sebagai respons, dan akhirnya mengambil detail tempat untuk tempat yang dipilih. Contoh ini juga menunjukkan penggunaan token sesi untuk mengelompokkan kueri pengguna dengan permintaan Place Details akhir.

TypeScript

let title;
let results;
let input;
let token;

// Add an initial request body.
let request = {
    input: "",
    locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ["restaurant"],
    language: "en-US",
    region: "us",
};

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

    title = document.getElementById('title');
    results = document.getElementById('results');
    input = document.querySelector("input");
    input.addEventListener("input", makeAcRequest);
    request = refreshToken(request) as any;
}

async function makeAcRequest(input) {
    // Reset elements and exit if an empty string is received.
    if (input.target.value == '') {
        title.innerText = '';
        results.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = input.target.value;

    // Fetch autocomplete suggestions and show them in a list.
    // @ts-ignore
    const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    title.innerText = 'Query predictions for "' + request.input + '"';

    // Clear the list first.
    results.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a link for the place, add an event handler to fetch the place.
        const a = document.createElement('a');
        a.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        a.innerText = placePrediction.text.toString();

        // Create a new list element.
        const li = document.createElement('li');
        li.appendChild(a);
        results.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    let placeText = document.createTextNode(place.displayName + ': ' + place.formattedAddress);
    results.replaceChildren(placeText);
    title.innerText = 'Selected Place:';
    input.value = '';
    refreshToken(request);
}

// Helper function to refresh the session token.
async function refreshToken(request) {
    // Create a new session token and add it to the request.
    token = new google.maps.places.AutocompleteSessionToken();
    request.sessionToken = token;
    return request;
}

declare global {
    interface Window {
      init: () => void;
    }
  }
  window.init = init;
index.ts

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

let title;
let results;
let input;
let token;
// Add an initial request body.
let request = {
  input: "",
  locationRestriction: {
    west: -122.44,
    north: 37.8,
    east: -122.39,
    south: 37.78,
  },
  origin: { lat: 37.7893, lng: -122.4039 },
  includedPrimaryTypes: ["restaurant"],
  language: "en-US",
  region: "us",
};

async function init() {
  token = new google.maps.places.AutocompleteSessionToken();
  title = document.getElementById("title");
  results = document.getElementById("results");
  input = document.querySelector("input");
  input.addEventListener("input", makeAcRequest);
  request = refreshToken(request);
}

async function makeAcRequest(input) {
  // Reset elements and exit if an empty string is received.
  if (input.target.value == "") {
    title.innerText = "";
    results.replaceChildren();
    return;
  }

  // Add the latest char sequence to the request.
  request.input = input.target.value;

  // Fetch autocomplete suggestions and show them in a list.
  // @ts-ignore
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(
      request,
    );

  title.innerText = 'Query predictions for "' + request.input + '"';
  // Clear the list first.
  results.replaceChildren();

  for (const suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a link for the place, add an event handler to fetch the place.
    const a = document.createElement("a");

    a.addEventListener("click", () => {
      onPlaceSelected(placePrediction.toPlace());
    });
    a.innerText = placePrediction.text.toString();

    // Create a new list element.
    const li = document.createElement("li");

    li.appendChild(a);
    results.appendChild(li);
  }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  let placeText = document.createTextNode(
    place.displayName + ": " + place.formattedAddress,
  );

  results.replaceChildren(placeText);
  title.innerText = "Selected Place:";
  input.value = "";
  refreshToken(request);
}

// Helper function to refresh the session token.
async function refreshToken(request) {
  // Create a new session token and add it to the request.
  token = new google.maps.places.AutocompleteSessionToken();
  request.sessionToken = token;
  return request;
}

window.init = init;
index.js

Catatan: JavaScript dikompilasi dari cuplikan TypeScript.

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

a {
  cursor: pointer;
  text-decoration: underline;
  color: blue;
}

input {
  width: 300px;
}
style.css

HTML

<html>
  <head>
    <title>Place Autocomplete Data API Session</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <input id="input" type="text" placeholder="Search for a place..." />
    <div id="title"></div>
    <ul id="results"></ul>
    <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=init&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Mencoba Contoh

JSFiddle.net Google Cloud Shell