Widget Place Autocomplete

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.

Widget Place Autocomplete membuat kolom input teks, memberikan prediksi tempat dalam daftar pilihan UI, dan menampilkan detail tempat sebagai respons terhadap pilihan pengguna. Gunakan Widget Place Autocomplete untuk menyematkan antarmuka pengguna pelengkapan otomatis mandiri yang lengkap di halaman web Anda. Untuk referensi API lengkap, lihat PlaceAutocompleteElement.

Prasyarat

Untuk menggunakan Place Autocomplete, Anda harus mengaktifkan Places API (New) di project Google Cloud Anda. Lihat bagian Memulai untuk mengetahui detailnya

Yang baru

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 dioptimalkan, termasuk dukungan untuk pembaca layar dan interaksi keyboard.
• Widget Autocomplete menampilkan class Place baru (referensi Place) untuk menyederhanakan penanganan objek yang ditampilkan.
• Dukungan yang lebih baik untuk perangkat seluler dan layar kecil.
• Performa dan tampilan grafis yang lebih baik.

Menambahkan widget Autocomplete

Widget Autocomplete membuat kolom input teks, memberikan prediksi tempat dalam daftar pilihan UI, dan menampilkan detail tempat sebagai respons terhadap klik pengguna menggunakan pemroses gmp-select. Bagian ini menampilkan cara menambahkan widget pelengkapan otomatis ke peta Google atau halaman web.

Menambahkan widget Autocomplete ke halaman web

Untuk menambahkan widget Autocomplete ke halaman web, buat google.maps.places.PlaceAutocompleteElement baru, lalu tambahkan ke halaman seperti yang ditunjukkan dalam contoh berikut:

TypeScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);
index.ts

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

// Request needed libraries.
const { PlaceAutocompleteElement } =
    await google.maps.importLibrary('places');
// Create the input HTML element, and append it.
const placeAutocomplete = new PlaceAutocompleteElement();
document.body.appendChild(placeAutocomplete);
index.js

Lihat contoh kode lengkap

Menambahkan widget Autocomplete ke peta

Jika alamat penagihan Anda berada di luar Wilayah Ekonomi Eropa (EEA), Anda juga dapat menggunakan widget Autocomplete dengan Google Maps.

Untuk menambahkan widget Autocomplete ke peta, minta library yang diperlukan terlebih dahulu, seperti yang ditunjukkan di sini:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

Kemudian, di HTML Anda, tempatkan elemen gmp-place-autocomplete baru di dalam div, dan tempatkan div tersebut di dalam gmp-map, seperti yang ditunjukkan dalam contoh berikut:

<gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
    <div
        class="place-autocomplete-card"
        slot="control-inline-start-block-start">
        <gmp-place-autocomplete
            placeholder="Search for a place..."></gmp-place-autocomplete>
    </div>
</gmp-map>
index.html

Untuk menambahkan widget Autocomplete ke peta secara terprogram, buat instance google.maps.places.PlaceAutocompleteElement baru, tambahkan PlaceAutocompleteElement ke div, dan terapkan atribut slot ke div, seperti yang ditunjukkan dalam contoh berikut:

// In your TS or JS, request the needed libraries.
const { PlaceAutocompleteElement } = await google.maps.importLibrary("places");

// Get the map element.
const mapElement = document.querySelector('gmp-map') as google.maps.MapElement;

// Create the PlaceAutocompleteElement instance.
const placeAutocomplete = new PlaceAutocompleteElement({});

// Create a div and append the PlaceAutocompleteElement to it.
const card = document.createElement("div");
card.appendChild(placeAutocomplete);

// Apply the slot attribute to the div.
// This positions the control in the top-left corner of the map.
card.setAttribute("slot", "control-inline-start-block-start");

// Append the div to the map element (check for null).
if (mapElement) {
    mapElement.appendChild(card);
}

Lihat contoh kode lengkap

Menambahkan teks placeholder

Gunakan properti placeholder untuk menambahkan teks placeholder. Contoh berikut menunjukkan cara menetapkan teks placeholder di HTML:

<gmp-place-autocomplete
  placeholder="Search for a place..."
></gmp-place-autocomplete>

Anda juga dapat menetapkan teks placeholder secara terprogram:

placeAutocomplete.placeholder = 'Search for a place...';

Membatasi prediksi pelengkapan otomatis

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

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 meter), atau area pandang yang membentang di globe.

Membatasi penelusuran tempat menurut negara

Untuk membatasi penelusuran tempat ke satu atau beberapa negara tertentu, gunakan properti includedRegionCodes untuk menentukan kode negara seperti yang ditampilkan dalam cuplikan berikut (dengan asumsi Anda telah membuat instance bernama placeAutocomplete):

placeAutocomplete.includedRegionCodes = ['us', 'au'];;

Membatasi penelusuran tempat ke batas peta

Untuk membatasi Place Search ke batas peta, gunakan properti locationRestriction. Cuplikan berikut menunjukkan cara menambahkan pemroses untuk memperbarui batas saat batas tersebut berubah:

// Use the bounds_changed event to restrict results to the current map bounds.
google.maps.event.addListener(innerMap, 'bounds_changed', async () => {
    placeAutocomplete.locationRestriction = innerMap.getBounds();
});

Untuk menghapus locationRestriction, tetapkan parameter ini ke null.

Membiaskan hasil penelusuran tempat

Biaskan hasil penelusuran tempat ke area lingkaran dengan menggunakan properti locationBias, seperti yang ditampilkan di sini:

placeAutocomplete.locationBias = {radius: 100, center: {lat: 40.749933, lng: -73.98633}};

Untuk menghapus locationBias, tetapkan parameter ini ke null.

Membatasi hasil penelusuran tempat ke jenis tertentu

Batasi hasil penelusuran tempat ke jenis tempat tertentu dengan menggunakan properti includedPrimaryTypes, dan menentukan satu atau beberapa jenis, seperti yang ditampilkan di sini:

const autocomplete = new google.maps.places.PlaceAutocompleteElement({
  includedPrimaryTypes: ['establishment'],
});

Untuk mengetahui daftar lengkap jenis yang didukung, lihat Tabel jenis tempat A dan B.

Mendapatkan detail tempat

Guna mendapatkan Place Details untuk tempat yang dipilih, tambahkan pemroses gmp-select ke PlaceAutocompleteElement, seperti yang ditampilkan dalam contoh berikut:

TypeScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({
        placePrediction,
    }: google.maps.places.PlacePredictionSelectEvent) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);
index.ts

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

// Add the gmp-select listener, and display the results.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: ['displayName', 'formattedAddress', 'location'],
        });
        selectedPlaceTitle.textContent = 'Selected Place:';
        selectedPlaceInfo.textContent = JSON.stringify(
            place.toJSON(),
            /* replacer */ null,
            /* space */ 2
        );
    }
);
index.js

Lihat contoh kode lengkap

Dalam contoh sebelumnya, pemroses peristiwa menerima PlacePredictionSelectEvent dan memanggil placePrediction.toPlace() untuk mendapatkan instance class Place (referensi Place). Panggil place.fetchFields() guna mendapatkan kolom data Place Details yang diperlukan untuk aplikasi Anda.

Pemroses dalam contoh berikutnya meminta kolom displayName, formattedAddress, location, dan viewport di place.fetchFields(), lalu menggunakan place.viewport dengan fitBounds() untuk menampilkan tempat yang dipilih di peta.

TypeScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

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

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

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

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

// Add the gmp-select listener, and display the results on the map.
placeAutocomplete.addEventListener(
    'gmp-select',
    async ({ placePrediction }) => {
        const place = placePrediction.toPlace();
        await place.fetchFields({
            fields: [
                'displayName',
                'formattedAddress',
                'location',
                'viewport',
            ],
        });

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

        const content = document.createElement('div');
        const nameText = document.createElement('span');
        nameText.textContent = place.displayName ?? 'No name';
        content.appendChild(nameText);
        content.appendChild(document.createElement('br'));
        const addressText = document.createElement('span');
        addressText.textContent = place.formattedAddress ?? 'No address';
        content.appendChild(addressText);

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

Lihat contoh kode lengkap

Contoh peta

Bagian ini berisi kode lengkap untuk contoh peta yang ditampilkan pada halaman ini.

Elemen Autocomplete

Contoh ini menambahkan widget Autocomplete ke halaman web, dan menampilkan hasil untuk setiap tempat yang dipilih.

TypeScript

async function init(): Promise<void> {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({
            placePrediction,
        }: google.maps.places.PlacePredictionSelectEvent) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

void init();
index.ts

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

async function init() {
    // Request needed libraries.
    const { PlaceAutocompleteElement } =
        await google.maps.importLibrary('places');
    // Create the input HTML element, and append it.
    const placeAutocomplete = new PlaceAutocompleteElement();
    document.body.appendChild(placeAutocomplete);

    // Inject HTML UI.
    const selectedPlaceTitle = document.createElement('p');
    selectedPlaceTitle.textContent = '';
    document.body.appendChild(selectedPlaceTitle);

    const selectedPlaceInfo = document.createElement('pre');
    selectedPlaceInfo.textContent = '';
    document.body.appendChild(selectedPlaceInfo);

    // Add the gmp-select listener, and display the results.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: ['displayName', 'formattedAddress', 'location'],
            });
            selectedPlaceTitle.textContent = 'Selected Place:';
            selectedPlaceInfo.textContent = JSON.stringify(
                place.toJSON(),
                /* replacer */ null,
                /* space */ 2
            );
        }
    );
}

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

p {
    font-family: Roboto, sans-serif;
    font-weight: bold;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete element</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <p style="font-family: roboto, sans-serif">Search for a place here:</p>
    </body>
</html>
index.html

Menambahkan Autocomplete ke peta

Contoh ini menampilkan cara menambahkan widget Autocomplete ke peta Google.

TypeScript

const mapElement = document.querySelector('gmp-map')!;
const placeAutocomplete = document.querySelector('gmp-place-autocomplete')!;
let innerMap: google.maps.Map;
let marker: google.maps.marker.AdvancedMarkerElement;
let infoWindow: google.maps.InfoWindow;
async function init(): Promise<void> {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds()!;
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

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

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

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

// Helper function to create an info window.
function updateInfoWindow(
    content: string | Element | Text | null | undefined,
    center: google.maps.LatLng | google.maps.LatLngLiteral | null | undefined
) {
    infoWindow.setContent(content);
    infoWindow.setPosition(center);
    infoWindow.open({
        map: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void init();
index.ts

Catatan: Baca panduan cara menggunakan TypeScript dan Google Maps.

JavaScript

const mapElement = document.querySelector('gmp-map');
const placeAutocomplete = document.querySelector('gmp-place-autocomplete');
let innerMap;
let marker;
let infoWindow;
async function init() {
    // Request needed libraries.
    const [{ AdvancedMarkerElement }, { InfoWindow }] = await Promise.all([
        google.maps.importLibrary('marker'),
        google.maps.importLibrary('maps'),
        google.maps.importLibrary('places'),
    ]);

    // Get the inner map.
    innerMap = mapElement.innerMap;
    innerMap.setOptions({
        mapTypeControl: false,
    });

    // Use the bounds_changed event to restrict results to the current map bounds.
    innerMap.addListener('bounds_changed', () => {
        placeAutocomplete.locationRestriction = innerMap.getBounds();
    });

    // Create the marker and infoWindow.
    marker = new AdvancedMarkerElement({
        map: innerMap,
    });

    infoWindow = new InfoWindow();

    // Add the gmp-select listener, and display the results on the map.
    placeAutocomplete.addEventListener(
        'gmp-select',
        async ({ placePrediction }) => {
            const place = placePrediction.toPlace();
            await place.fetchFields({
                fields: [
                    'displayName',
                    'formattedAddress',
                    'location',
                    'viewport',
                ],
            });

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

            const content = document.createElement('div');
            const nameText = document.createElement('span');
            nameText.textContent = place.displayName ?? 'No name';
            content.appendChild(nameText);
            content.appendChild(document.createElement('br'));
            const addressText = document.createElement('span');
            addressText.textContent = place.formattedAddress ?? 'No address';
            content.appendChild(addressText);

            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: innerMap,
        anchor: marker,
        shouldFocus: false,
    });
}

void 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-autocomplete-card {
    background-color: #fff;
    border-radius: 5px;
    box-shadow: rgba(0, 0, 0, 0.35) 0px 5px 15px;
    margin: 10px;
    padding: 5px;
    font-family: Roboto, sans-serif;
    font-size: small;
}

gmp-place-autocomplete {
    width: 300px;
}

#infowindow-content .title {
    font-weight: bold;
}

#map #infowindow-content {
    display: inline;
}
style.css

HTML

<html>
    <head>
        <title>Place Autocomplete map</title>

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <script>
            // prettier-ignore
            (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: "GOOGLE_MAPS_API_KEY"
            });
        </script>
    </head>
    <body>
        <gmp-map center="40.749933,-73.98633" zoom="13" map-id="DEMO_MAP_ID">
            <div
                class="place-autocomplete-card"
                slot="control-inline-start-block-start">
                <gmp-place-autocomplete
                    placeholder="Search for a place..."></gmp-place-autocomplete>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Pengoptimalan Autocomplete (New)

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

Berikut ini beberapa pedoman umum:

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

Pengoptimalan biaya lanjutan

Pertimbangkan implementasi Autocomplete (New) yang terprogram untuk mengakses SKU: Autocomplete Request pricing dan meminta hasil Geocoding API tentang tempat yang dipilih, bukan Place Details (New). 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 dan bujur atau alamat tempat yang dipilih pengguna, Geocoding API akan mengirimkan informasi ini dengan biaya yang lebih murah daripada panggilan Place Details (New).
• Jika pengguna memilih prediksi pelengkapan otomatis dalam rata-rata empat permintaan prediksi Autocomplete (New) atau kurang, harga per permintaan dapat lebih hemat biaya daripada harga per sesi.

Untuk memilih penerapan Autocomplete (New) yang paling hemat biaya untuk aplikasi Anda, temukan baris dalam tabel berikut yang sesuai dengan kebutuhan aplikasi Anda.

Yang dibutuhkan aplikasi Anda	Rata-rata permintaan Autocomplete (Baru) sebelum pengguna memilih prediksi	Penerapan yang direkomendasikan
Detail tempat selain alamat dan lokasi, seperti nama tempat, status bisnis, atau jam buka	Berapa saja	Autocomplete (New) berbasis sesi dengan Place Details (New)
Hanya alamat dan lintang/bujur dari prediksi yang dipilih	Empat atau kurang	Autocomplete (New) per permintaan dengan Geocoding API
Hanya alamat dan lintang/bujur dari prediksi yang dipilih	Lebih dari empat	Autocomplete (New) berbasis sesi untuk aplikasi khusus alamat

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

Untuk menemukan jumlah rata-rata permintaan untuk tabel, analisis rata-rata jumlah karakter yang diketik pengguna sebelum memilih prediksi Autocomplete (New) di aplikasi Anda.

Autocomplete (New) berbasis sesi dengan Place Details (New)

Gunakan Autocomplete (New) berbasis sesi dengan Place Details (New).
Karena aplikasi Anda memerlukan Place Details (New), seperti nama tempat, status bisnis, atau jam buka, penerapan Autocomplete (New) Anda harus menggunakan token sesi (secara terprogram atau terintegrasi ke dalam widget JavaScript, Android, atau iOS) per sesi ditambah SKU Places yang berlaku, 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 Autocomplete (New) dan permintaan Place Details (New) pada prediksi yang dipilih. Pastikan untuk menentukan parameter fields untuk memastikan Anda hanya meminta kolom data Autocomplete (New) yang Anda butuhkan.

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

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

Autocomplete (New) per permintaan dengan Geocoding API

Terapkan Autocomplete (New) 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 Requests ditambah panggilan Geocoding API tentang prediksi tempat yang dipilih lebih murah daripada biaya per sesi Autocomplete (New) per sesi.¹

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

Autocomplete (New) berbasis sesi untuk aplikasi khusus alamat

Gunakan Autocomplete (New) berbasis sesi dengan Place Details (New).
Karena rata-rata jumlah permintaan yang Anda perkirakan akan dibuat sebelum pengguna memilih prediksi Autocomplete (New) melebihi biaya harga per sesi, implementasi Autocomplete (New) Anda harus menggunakan token sesi untuk permintaan Autocomplete (New) dan permintaan Place Details (New) terkait per sesi. ¹

Penerapan widget
Pengelolaan sesi secara otomatis terintegrasi ke dalam widget JavaScript, Android, atau iOS. Ini mencakup permintaan Autocomplete (New) dan permintaan Place Details (New) 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 (New) Anda. Saat meminta Place Details (New) tentang prediksi yang dipilih, sertakan parameter berikut:

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

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

Jika permintaan yang tertunda dapat menghasilkan permintaan terprogram rata-rata di bawah empat, Anda dapat mengikuti panduan ini untuk penerapan Autocomplete (New) 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 (New):

• Tambahkan pembatasan negara, pembiasan lokasi, dan (untuk penerapan terprogram) preferensi bahasa ke penerapan Autocomplete (New) Anda. Preferensi bahasa tidak diperlukan dengan widget karena widget tersebut memilih preferensi bahasa dari browser atau perangkat seluler pengguna.
• Jika Autocomplete (New) disertai sebuah peta, Anda dapat membiaskan lokasi berdasarkan area pandang peta.
• Jika pengguna tidak memilih salah satu prediksi Autocomplete (New), 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 (New). Jika hasil hanya diharapkan di wilayah tertentu, gunakan pembiasan lokasi.
  Skenario lain saat Anda sebaiknya beralih kembali ke Geocoding API mencakup:
  • Pengguna yang memasukkan alamat sub-premis, 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.

Pembiasan lokasi

Biasakan hasil ke area yang ditentukan dengan meneruskan parameter location dan parameter radius. Tindakan ini akan menginstruksikan Autocomplete (New) untuk memprioritaskan menampilkan hasil dalam area yang ditentukan. Hasil di luar area yang ditentukan mungkin tetap ditampilkan. Anda dapat menggunakan parameter includedRegionCodes untuk memfilter hasil agar hanya menampilkan tempat dalam negara yang ditentukan.

Peringatan: Jika radius tidak diberikan, parameter location akan diabaikan.

Hasil tempat usaha umumnya tidak memiliki peringkat yang cukup tinggi untuk ditampilkan dalam hasil saat area penelusuran luas. Jika Anda ingin tempat usaha muncul dalam hasil campuran tempat usaha/geocode, Anda dapat menentukan radius yang lebih kecil. Atau, gunakan types=establishment untuk membatasi hasil hanya pada tempat usaha.

Pembatasan lokasi

Batasi hasil ke area yang ditentukan dengan meneruskan parameter locationRestriction.

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

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.