Place Autocomplete Data API

Developer Wilayah Ekonomi Eropa (EEA)

Place Autocomplete Data API memungkinkan Anda mengambil prediksi tempat secara terprogram, untuk membuat 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 Place Autocomplete Data API untuk membuat permintaan pelengkapan otomatis berdasarkan kueri pengguna.

Contoh berikut menunjukkan integrasi saran penelusuran yang disederhanakan. Masukkan kueri penelusuran Anda, seperti "pizza" atau "poke", lalu klik untuk memilih hasil yang Anda inginkan.

Permintaan Pelengkapan Otomatis

Permintaan pelengkapan otomatis 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 umum, nilai ini akan diperbarui saat pengguna mengetik kueri. Permintaan harus menyertakan sessionToken, yang digunakan untuk tujuan penagihan.

Cuplikan berikut menunjukkan cara membuat isi permintaan dan menambahkan 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 dari mana jarak geodetik ke tujuan akan dihitung. Jika nilai ini tidak disertakan, jarak tidak akan ditampilkan.

Gunakan properti includedPrimaryTypes untuk menentukan hingga lima jenis tempat. Jika tidak ada jenis yang ditentukan, tempat dari semua jenis 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 disertakan secara otomatis). 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 berakhir 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 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 berakhir saat fetchFields() dipanggil. Setelah membuat instance Place, Anda tidak perlu meneruskan token sesi ke fetchFields() karena hal ini ditangani secara otomatis. 

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

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

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 menggunakan token yang sama untuk lebih dari satu sesi, setiap permintaan akan ditagih satu per satu.

Anda dapat memilih untuk tidak menyertakan token sesi pelengkapan otomatis dari permintaan. Jika token sesi tidak disertakan, setiap permintaan 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 dipanggil setiap beberapa penekanan tombol (bukan per karakter), dan daftar kemungkinan hasil ditampilkan. Saat pengguna membuat pilihan dari daftar hasil, pilihan tersebut dihitung sebagai permintaan, dan semua permintaan yang dibuat selama penelusuran digabungkan dan dihitung sebagai satu permintaan. Jika pengguna memilih tempat, kueri penelusuran tersedia tanpa biaya, dan hanya permintaan data Tempat yang dikenai biaya. Jika pengguna tidak membuat pilihan dalam beberapa menit setelah sesi dimulai, hanya kueri penelusuran yang ditagih.

Dari perspektif aplikasi, alur peristiwanya adalah sebagai berikut:

  1. Pengguna mulai mengetik kueri untuk menelusuri "Paris, Prancis".
  2. Setelah mendeteksi input pengguna, aplikasi membuat token sesi baru, "Token A".
  3. Saat pengguna mengetik, API akan membuat permintaan pelengkapan otomatis setiap beberapa karakter, menampilkan daftar baru hasil yang mungkin 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 diwakili oleh "Token A", sebagai satu permintaan.
    • Pilihan pengguna dihitung sebagai permintaan Place Detail, dan ditambahkan ke sesi yang diwakili oleh "Token A".
  5. Sesi selesai, dan aplikasi membuang "Token A".
Pelajari cara penagihan sesi

Kode contoh lengkap

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

Prediksi pelengkapan otomatis tempat

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

TypeScript

async function init() {
    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 + '":'
        )
    );

    const resultsElement = document.getElementById('results') as HTMLElement;

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

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

        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

JavaScript

async function init() {
    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 + '":'));
    const resultsElement = document.getElementById('results');
    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        // Create a new list element.
        const listItem = document.createElement('li');
        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

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>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>
index.html

Mencoba Contoh

Prediksi ketikan pelengkapan otomatis tempat dengan sesi

Contoh ini menunjukkan konsep berikut:

  • Memanggil fetchAutocompleteSuggestions() berdasarkan kueri pengguna dan menampilkan daftar tempat yang diprediksi sebagai respons.
  • Menggunakan token sesi untuk mengelompokkan kueri pengguna dengan permintaan Place Details akhir.
  • Mengambil detail tempat untuk tempat yang dipilih dan menampilkan penanda.
  • Menggunakan penempatan kontrol untuk menyusun elemen UI dalam elemen gmp-map.

TypeScript

const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let titleElement = document.querySelector('.title') as HTMLElement;
let resultsContainerElement = document.querySelector('.results') as HTMLElement;
let inputElement = document.querySelector('input') as HTMLInputElement;
let tokenStatusElement = document.querySelector('.token-status') as HTMLElement;
let newestRequestId = 0;
let tokenCount = 0;

// Create an initial request body.
const request: google.maps.places.AutocompleteRequest = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};

async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });

    inputElement.addEventListener('input', makeAutocompleteRequest);
}

async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;

    const { AutocompleteSuggestion } = (await google.maps.importLibrary(
        'places'
    )) as google.maps.PlacesLibrary;

    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = (inputEvent.target as HTMLInputElement).value;

    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } =
        await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId) return;

    titleElement.innerText = `Place predictions for "${request.input}"`;

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

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

        if (!placePrediction) {
            continue;
        }

        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');

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

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place: google.maps.places.Place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary(
        'marker'
    )) as google.maps.MarkerLibrary;

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

    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';

    await refreshToken();

    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }

    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });

    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}

// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary(
        'places'
    )) as google.maps.PlacesLibrary;

    // Increment the token counter.
    tokenCount++;

    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}

init();
index.ts

JavaScript

const mapElement = document.querySelector('gmp-map');
let innerMap;
let marker;
let titleElement = document.querySelector('.title');
let resultsContainerElement = document.querySelector('.results');
let inputElement = document.querySelector('input');
let tokenStatusElement = document.querySelector('.token-status');
let newestRequestId = 0;
let tokenCount = 0;
// Create an initial request body.
const request = {
    input: '',
    includedPrimaryTypes: [
        'restaurant',
        'cafe',
        'museum',
        'park',
        'botanical_garden',
    ],
};
async function init() {
    await google.maps.importLibrary('maps');
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });
    // Update request center and bounds when the map bounds change.
    google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
        request.locationRestriction = innerMap.getBounds();
        request.origin = innerMap.getCenter();
    });
    inputElement.addEventListener('input', makeAutocompleteRequest);
}
async function makeAutocompleteRequest(inputEvent) {
    // To avoid race conditions, store the request ID and compare after the request.
    const requestId = ++newestRequestId;
    const { AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    if (!inputEvent.target?.value) {
        titleElement.textContent = '';
        resultsContainerElement.replaceChildren();
        return;
    }
    // Add the latest char sequence to the request.
    request.input = inputEvent.target.value;
    // Fetch autocomplete suggestions and show them in a list.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    // If the request has been superseded by a newer request, do not render the output.
    if (requestId !== newestRequestId)
        return;
    titleElement.innerText = `Place predictions for "${request.input}"`;
    // Clear the list first.
    resultsContainerElement.replaceChildren();
    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        if (!placePrediction) {
            continue;
        }
        // Create a link for the place, add an event handler to fetch the place.
        // We are using a button element to take advantage of its a11y capabilities.
        const placeButton = document.createElement('button');
        placeButton.addEventListener('click', () => {
            onPlaceSelected(placePrediction.toPlace());
        });
        placeButton.textContent = placePrediction.text.toString();
        placeButton.classList.add('place-button');
        // Create a new list item element.
        const li = document.createElement('li');
        li.appendChild(placeButton);
        resultsContainerElement.appendChild(li);
    }
}
// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    const { AdvancedMarkerElement } = (await google.maps.importLibrary('marker'));
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress', 'location'],
    });
    resultsContainerElement.textContent = `${place.displayName}: ${place.formattedAddress}`;
    titleElement.textContent = 'Selected Place:';
    inputElement.value = '';
    await refreshToken();
    // Remove the previous marker, if it exists.
    if (marker) {
        marker.remove();
    }
    // Create a new marker.
    marker = new AdvancedMarkerElement({
        map: innerMap,
        position: place.location,
        title: place.displayName,
    });
    // Center the map on the selected place.
    if (place.location) {
        innerMap.setCenter(place.location);
        innerMap.setZoom(15);
    }
}
// Helper function to refresh the session token.
async function refreshToken() {
    const { AutocompleteSessionToken } = (await google.maps.importLibrary('places'));
    // Increment the token counter.
    tokenCount++;
    // Create a new session token and add it to the request.
    request.sessionToken = new AutocompleteSessionToken();
    tokenStatusElement.textContent = `Session token count: ${tokenCount}`;
}
init();
index.js

CSS

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

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

.place-button {
    height: 3rem;
    width: 100%;
    background-color: transparent;
    text-align: left;
    border: none;
    cursor: pointer;
}

.place-button:focus-visible {
    outline: 2px solid #0056b3;
    border-radius: 2px;
}

.input {
    width: 300px;
    font-size: small;
    margin-bottom: 1rem;
}

/* Styles for the floating panel */
.controls {
    background-color: #fff;
    border-radius: 8px;
    box-shadow: 0 2px 6px rgba(0, 0, 0, 0.3);
    font-family: sans-serif;
    font-size: small;
    margin: 12px;
    padding: 1rem;
}

.title {
    font-weight: bold;
    margin-top: 1rem;
    margin-bottom: 0.5rem;
}

.results {
    list-style-type: none;
    margin: 0;
    padding: 0;
}

.results li:not(:last-child) {
    border-bottom: 1px solid #ddd;
}

.results li:hover {
    background-color: #eee;
}

style.css

HTML

<html>
    <head>
        <title>Place Autocomplete Data API Session</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- 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: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map center="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Mencoba Contoh

Pengoptimalan Pelengkapan Otomatis (Baru)

Bagian ini menjelaskan praktik terbaik untuk membantu Anda memaksimalkan layanan Autocomplete (Baru).

Berikut ini beberapa pedoman umum:

  • Cara tercepat untuk mengembangkan antarmuka pengguna yang berfungsi baik adalah dengan menggunakan widget Autocomplete (Baru) Maps JavaScript API, widget Autocomplete (Baru) Places SDK for Android, atau widget Autocomplete (Baru) Places SDK for iOS.
  • Pahami kolom data Pelengkapan Otomatis (Baru) 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 Autocomplete (Baru), gunakan mask kolom dalam widget Place Details (Baru) dan Autocomplete (Baru) agar hanya menampilkan kolom data Autocomplete (Baru) yang Anda butuhkan.

Pengoptimalan biaya lanjutan

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

  • Jika Anda hanya memerlukan lintang/bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini dengan biaya yang lebih murah daripada panggilan Place Details (Baru).
  • Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete (Baru) atau kurang, harga per permintaan mungkin lebih hemat biaya daripada harga per sesi.
Untuk mendapatkan bantuan dalam memilih penerapan Pelengkapan Otomatis (Baru) 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 Autocomplete (Baru) berbasis sesi dengan Place Details (Baru).
Karena aplikasi Anda memerlukan Place Details (Baru), seperti nama tempat, status bisnis, atau jam buka, penerapan Autocomplete (Baru) Anda harus menggunakan token sesi (secara terprogram atau bawaan di widget JavaScript, Android, atau iOS) per session ditambah SKU Places yang berlaku, bergantung pada kolom data tempat yang Anda minta.1

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

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

  1. ID tempat dari respons Autocomplete (Baru)
  2. Token sesi yang digunakan dalam permintaan Autocomplete (Baru)
  3. Parameter fields yang menentukan kolom data Autocomplete (Baru) yang Anda butuhkan

Tidak, hanya memerlukan alamat dan lokasi

Geocoding API dapat menjadi opsi yang lebih hemat biaya daripada Place Details (Baru) untuk aplikasi Anda, bergantung pada performa penggunaan Autocomplete (Baru). Efisiensi Autocomplete (Baru) 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 Autocomplete (Baru) di aplikasi Anda.

Apakah pengguna Anda rata-rata memilih prediksi Autocomplete (Baru) dalam empat permintaan atau kurang?

Ya

Terapkan Autocomplete (Baru) secara terprogram tanpa token sesi dan panggil Geocoding API di prediksi tempat yang dipilih.
Geocoding API memberikan alamat dan koordinat lintang/bujur. Membuat empat permintaan Autocomplete ditambah panggilan Geocoding API tentang prediksi tempat yang dipilih lebih rendah daripada biaya per sesi Autocomplete (Baru) per sesi.1

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

Tidak

Gunakan Autocomplete (Baru) berbasis sesi dengan Place Details (Baru).
Karena rata-rata jumlah permintaan yang Anda harapkan sebelum pengguna memilih prediksi Autocomplete (Baru) melebihi biaya harga per sesi, penerapan Autocomplete (Baru) Anda harus menggunakan token sesi untuk permintaan Autocomplete (Baru) dan permintaan Place Details (Baru) terkait per sesi. 1

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

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

  1. ID tempat dari respons Autocomplete (Baru)
  2. Token sesi yang digunakan dalam permintaan Autocomplete (Baru)
  3. Parameter fields yang menentukan kolom seperti alamat dan geometri

Pertimbangkan untuk menunda permintaan Pelengkapan Otomatis (Baru)
Anda dapat menggunakan strategi seperti menunda permintaan Pelengkapan Otomatis (Baru) hingga pengguna mengetik tiga atau empat karakter pertama, sehingga aplikasi Anda membuat lebih sedikit permintaan. Misalnya, membuat permintaan Autocomplete (Baru) untuk setiap karakter setelah pengguna mengetik karakter ketiga berarti jika pengguna mengetik tujuh karakter, lalu memilih prediksi yang Anda buat satu permintaan Geocoding API-nya, total biaya yang harus dibayar adalah 4 Autocomplete (Baru) Per Permintaan + Geocoding.1

Jika permintaan yang tertunda dapat menghasilkan permintaan terprogram rata-rata di bawah empat, Anda dapat mengikuti panduan ini untuk penerapan Autocomplete (Baru) 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. Untuk mengetahui biaya, lihat daftar harga Google Maps Platform.

Praktik terbaik performa

Panduan berikut menjelaskan cara mengoptimalkan performa Autocomplete (Baru):

  • Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Pelengkapan Otomatis (Baru) Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
  • Jika Autocomplete (Baru) disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
  • Jika pengguna tidak memilih salah satu prediksi Autocomplete (Baru), 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 Place Details (Baru). Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
    Skenario lain saat Anda sebaiknya beralih kembali ke Geocoding API mencakup:
    • Pengguna memasukkan alamat sub-tempat, seperti alamat untuk unit atau apartemen tertentu dalam sebuah gedung. Misalnya, alamat Ceko "Stroupežnického 3191/17, Praha" akan menghasilkan prediksi parsial di Autocomplete (Baru).
    • 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.

Penyesuaian lokasi

Membiaskan hasil ke area tertentu dengan meneruskan parameter location dan parameter radius. Tindakan ini menginstruksikan Autocomplete (Baru) untuk memilih menampilkan hasil dalam area yang ditentukan. Hasil di luar area yang ditentukan mungkin tetap ditampilkan. Anda dapat menggunakan parameter components untuk memfilter hasil guna menampilkan hanya tempat-tempat di negara tertentu.

Membatasi lokasi

Batasi hasil ke area tertentu dengan meneruskan parameter locationRestriction.

Anda juga dapat membatasi hasil ke wilayah yang ditentukan oleh parameter location dan radius, dengan menambahkan parameter locationRestriction. Hal ini menginstruksikan Autocomplete (Baru) untuk menampilkan hanya hasil dalam wilayah tersebut.