Widget di completamento automatico dei luoghi

Sviluppatori dello Spazio economico europeo (SEE)

Il widget Place Autocomplete crea un campo di immissione di testo, fornisce le previsioni sui luoghi in un elenco di selezione dell'UI e restituisce i dettagli Place Details in risposta alla selezione dell'utente. Utilizza il widget Place Autocomplete per incorporare un'interfaccia utente di completamento automatico completa e autonoma nella tua pagina web. Per il riferimento completo dell'API, consulta PlaceAutocompleteElement.

Prerequisiti

Per utilizzare Place Autocomplete, devi abilitare l'API Places (New) nel tuo progetto Google Cloud. Per maggiori dettagli, consulta la guida introduttiva.

Novità

Place Autocomplete è stato migliorato nei seguenti modi:

  • L'UI del widget di completamento automatico supporta la localizzazione regionale (incluse le lingue da destra a sinistra) per il segnaposto di input di testo, il logo dell'elenco delle previsioni e le previsioni sui luoghi.
  • Accessibilità migliorata, incluso il supporto per screen reader e interazione da tastiera.
  • Il widget di completamento automatico restituisce la nuova classe Place (Place riferimento) per semplificare la gestione dell'oggetto restituito.
  • Supporto migliorato per dispositivi mobili e schermi piccoli.
  • Prestazioni migliori e aspetto grafico migliorato.

Aggiungere un widget di completamento automatico

Il widget di completamento automatico crea un campo di immissione di testo, fornisce le previsioni sui luoghi in un elenco di selezione dell'UI e restituisce i dettagli sui luoghi in risposta a un clic dell'utente utilizzando il gmp-select listener. Questa sezione mostra come aggiungere un widget di completamento automatico a una pagina web o a una mappa Google.

Aggiungere un widget di completamento automatico a una pagina web

Per aggiungere il widget di completamento automatico a una pagina web, crea un nuovo google.maps.places.PlaceAutocompleteElement, e aggiungilo alla pagina come mostrato nell'esempio seguente:

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

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

Visualizza l'esempio di codice completo

Aggiungere un widget di completamento automatico a una mappa

Se il tuo indirizzo di fatturazione si trova al di fuori dello Spazio economico europeo (SEE), puoi utilizzare il widget di completamento automatico anche con una mappa Google.

Per aggiungere un widget di completamento automatico a una mappa, richiedi prima le librerie necessarie, come mostrato di seguito:

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

Poi, nel codice HTML, nidifica un nuovo gmp-place-autocomplete elemento all'interno di un div e nidifica il div all'interno di un gmp-map, come mostrato nell' esempio seguente:

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

Per aggiungere un widget di completamento automatico a una mappa in modo programmatico, crea una nuova google.maps.places.PlaceAutocompleteElement istanza, aggiungi PlaceAutocompleteElement a un div e applica l'attributo slot al div, come mostrato nell'esempio seguente:

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

Visualizza l'esempio di codice completo

Aggiungere testo segnaposto

Utilizza la placeholder proprietà per aggiungere testo segnaposto. L'esempio seguente mostra come impostare il testo segnaposto in HTML:

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

Puoi anche impostare il testo segnaposto in modo programmatico:

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

Limitare le previsioni di completamento automatico

Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luoghi, con una preferenza per le previsioni vicino alla posizione dell'utente, e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta PlaceAutocompleteElementOptions per presentare previsioni più pertinenti, limitando o influenzando i risultati.

La limitazione dei risultati fa sì che il widget di completamento automatico ignori tutti i risultati al di fuori dell' area di limitazione. Una pratica comune è limitare i risultati ai limiti della mappa. L'influenza dei risultati fa sì che il widget di completamento automatico mostri i risultati all'interno dell'area specificata, ma alcune corrispondenze potrebbero trovarsi al di fuori di quest'area.

Se non fornisci limiti o un'area visibile della mappa, l'API tenterà di rilevare la posizione dell'utente dal suo indirizzo IP e influenzerà i risultati in base a questa posizione. Imposta i limiti quando possibile. In caso contrario, utenti diversi potrebbero ricevere previsioni diverse. Inoltre, per migliorare in generale le previsioni, è importante fornire un'area visibile ragionevole, ad esempio una che hai impostato tramite panoramica o zoom sulla mappa, oppure un'area visibile impostata dallo sviluppatore in base alla posizione e al raggio del dispositivo. Quando un raggio non è disponibile, 5 km sono considerati un valore predefinito ragionevole per Place Autocomplete. Non impostare un'area visibile con raggio zero (un singolo punto), un'area visibile di pochi metri (meno di 100 metri) o un'area visibile che si estende su tutto il mondo.

Limitare la ricerca di luoghi per paese

Per limitare la ricerca di luoghi a uno o più paesi specifici, utilizza la includedRegionCodes proprietà per specificare i codici paese, come mostrato nello snippet seguente (si presuppone che tu abbia già creato un'istanza denominata placeAutocomplete):

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

Limitare la ricerca di luoghi ai limiti della mappa

Per limitare la ricerca di luoghi ai limiti di una mappa, utilizza la locationRestriction proprietà. Lo snippet seguente mostra come aggiungere un listener per aggiornare i limiti quando cambiano:

// 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();
});

Per rimuovere locationRestriction, impostalo su null.

Influenzare i risultati della ricerca di luoghi

Influenza i risultati della ricerca di luoghi in base a un'area circolare utilizzando la locationBias proprietà, come mostrato di seguito:

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

Per rimuovere locationBias, impostalo su null.

Limitare i risultati della ricerca di luoghi a determinati tipi

Limita i risultati della ricerca di luoghi a determinati tipi di luoghi utilizzando la includedPrimaryTypes proprietà e specificando uno o più tipi, come mostrato di seguito:

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

Per un elenco completo dei tipi supportati, consulta le tabelle A e B dei tipi di luoghi.

Visualizzare i dettagli sui luoghi

Per visualizzare i dettagli sui luoghi per il luogo selezionato, aggiungi un gmp-select listener a PlaceAutocompleteElement, come mostrato nell'esempio seguente:

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

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

Visualizza l'esempio di codice completo

Nell'esempio precedente, il listener di eventi riceve un PlacePredictionSelectEvent e chiama placePrediction.toPlace() per ottenere un'istanza della classe Place (riferimentoPlace ). Chiama place.fetchFields() per ottenere i campi di dati di Place Details necessari per la tua applicazione.

Il listener nell'esempio successivo richiede i campi displayName, formattedAddress, location, e viewport in place.fetchFields(), quindi utilizza place.viewport con fitBounds() per visualizzare il luogo selezionato su una mappa.

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

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

Visualizza l'esempio di codice completo

Mappe di esempio

Questa sezione contiene il codice completo per le mappe di esempio presentate in questa pagina.

Elemento di completamento automatico

Questo esempio aggiunge un widget di completamento automatico a una pagina web e visualizza i risultati per ogni luogo selezionato.

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();

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();

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

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>

Mappa di completamento automatico

Questo esempio mostra come aggiungere un widget di completamento automatico a una mappa 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();

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();

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

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>

Ottimizzazione del completamento automatico (New)

Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio di completamento automatico (New).

Ecco alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è usare il widget di completamento automatico (New) dell'API Maps JavaScript, il widget di completamento automatico (New) di Places SDK per Android, o il widget di completamento automatico (New) di Places SDK per iOS.
  • Comprendi fin da subito i campi di dati essenziali del completamento automatico (New)
  • I campi di influenza della posizione e di limitazione della posizione sono facoltativi, ma possono avere un impatto significativo sul rendimento del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che la tua app funzioni correttamente anche se l'API restituisce un errore.
  • Assicurati che la tua app gestisca i casi in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo dell'utilizzo del servizio di completamento automatico (New) , utilizza le maschere dei campi nei widget di dettagli sui luoghi (New) e di completamento automatico (New) per restituire solo i campi di datidi completamento automatico (New) di cui hai bisogno.

Ottimizzazione dei costi avanzata

Valuta la possibilità di implementare il completamento automatico (New) in modo programmatico per accedere a prezzo dello SKU: richiesta di completamento automatico e richiedere i risultati dell'API Geocoding sul luogo selezionato anziché sui dettagli sui luoghi (New). Il prezzo per richiesta abbinato all'API Geocoding è più conveniente del prezzo per sessione (basato sulla sessione) se vengono soddisfatte entrambe le seguenti condizioni:

  • Se hai bisogno solo della latitudine e della longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata a Place Details (New).
  • Se gli utenti selezionano una previsione di completamento automatico in media entro quattro richieste di previsioni di completamento automatico (New) o meno, il prezzo per richiesta può essere più conveniente del prezzo per sessione.
Per scegliere l'implementazione del completamento automatico (New) più adatta alle tue esigenze, seleziona la scheda corrispondente alla tua risposta alla seguente domanda.

La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?

Sì, servono altri dettagli

Utilizza il completamento automatico (New) basato sulla sessione con Place Details (New).
Poiché la tua applicazione richiede i dettagli sui luoghi (New), come il nome del luogo, lo stato dell'attività o gli orari di apertura, l'implementazione del completamento automatico (New) deve utilizzare un token di sessione (in modo programmatico o integrato nei JavaScript Android, iOS o iOS) per sessione più gli SKU di Places applicabili, a seconda dei campi di dati sui luoghi richiesti.1

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei JavaScript, Android, o iOS. Sono incluse sia le richieste di completamento automatico (New) sia la richiesta di dettagli sui luoghi (New) sulla previsione selezionata. Assicurati di specificare il fields parametro per richiedere solo i campi di datidi completamento automatico (New) di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste di completamento automatico (New). Quando richiedi i dettagli sui luoghi (New) sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo da la risposta di completamento automatico (New)
  2. Il token di sessione utilizzato nella richiesta di completamento automatico (New)
  3. Il parametro fields che specifica i campi di dati di completamento automatico (New) di cui hai bisogno

No, servono solo indirizzo e località

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (New) per la tua applicazione, a seconda del rendimento dell'utilizzo di Autocomplete (New). L'efficienza del completamento automatico (New) di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, di dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione del rendimento.

Per rispondere alla seguente domanda, analizza il numero medio di caratteri che un utente digita prima di selezionare una previsione di completamento automatico (New) nella tua applicazione.

In media, gli utenti selezionano una previsione di completamento automatico (New) in quattro o meno richieste?

Sì

Implementa il completamento automatico (New) in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione del luogo selezionato.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine. L'esecuzione di quattro richieste di completamento automatico richieste più una chiamata all'API Geocoding sulla previsione del luogo selezionato costa meno del costo per sessione del completamento automatico (New) per sessione.1

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che stanno cercando con un numero ancora inferiore di caratteri.

No

Utilizza il completamento automatico (New) basato sulla sessione con Place Details (New).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di completamento automatico (New) supera il costo del prezzo per sessione, l'implementazione del completamento automatico (New) deve utilizzare un token di sessione sia per le richieste di completamento automatico (New) sia per la richiesta di dettagli sui luoghi (New) associata per sessione. 1

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei JavaScript, Android, o iOS. Sono incluse sia le richieste di completamento automatico (New) sia la richiesta di dettagli sui luoghi (New) richiesta sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste di completamento automatico (New). Quando richiedi i dettagli sui luoghi (New) sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo da la risposta di completamento automatico (New)
  2. Il token di sessione utilizzato nella richiesta di completamento automatico (New)
  3. Il parametro fields che specifica campi come indirizzo e geometria

Valuta la possibilità di ritardare le richieste di completamento automatico (New)
Puoi utilizzare strategie come ritardare una richiesta di completamento automatico (New) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che la tua applicazione effettui meno richieste. Ad esempio, se effettui richieste di completamento automatico (New) per ogni carattere dopo che l'utente ha digitato il terzo carattere, se l'utente digita sette caratteri e poi seleziona una previsione per la quale effettui una richiesta dell'API Geocoding, il costo totale sarà per 4 completamenti automatici (New) per richiesta + Geocoding.1

Se il ritardo delle richieste può portare la media delle richieste programmatiche al di sotto di quattro, puoi seguire le indicazioni per l'implementazione del completamento automatico (New) con l'API Geocoding performant Autocomplete (New) with Geocoding API. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere le previsioni a ogni nuova pressione di un tasto.

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che stanno cercando con un numero inferiore di caratteri.


  1. Per i costi, consulta gli elenchi dei prezzi di Google Maps Platform.

Best practice per il rendimento

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento del completamento automatico (New):

  • Aggiungi limitazioni in base al paese, influenza della posizione, e (per le implementazioni programmatiche) preferenze sulla lingua all'implementazione del completamento automatico (New) . La preferenza della lingua non è necessaria con i widget, perché questi ultimi la selezionano dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico (New) è accompagnato da una mappa, puoi influenzare la posizione in base all'area visibile della mappa.
  • Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico (New), in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
    • Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
    • Se prevedi che l'utente inserisca query per un luogo specifico per nome o indirizzo, utilizza una richiesta di Place Details (New). Se i risultati sono previsti solo in una regione specifica, utilizza l'influenza della posizione.
    Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
    • Gli utenti che inseriscono indirizzi di sottolocalità, ad esempio indirizzi per unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" produce una previsione parziale nel completamento automatico (New).
    • Gli utenti che inseriscono indirizzi con prefissi di segmenti stradali come "23-30 29th St, Queens" a New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai nelle Hawaii.

Influenza della posizione

Influenza i risultati in base a un'area specificata passando un parametro location e un parametro radius. In questo modo, il completamento automatico (New) preferisce mostrare i risultati all'interno dell'area definita. I risultati al di fuori dell'area definita potrebbero comunque essere visualizzati. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.

Limitazione della posizione

Limita i risultati a un'area specificata passando un parametro locationRestriction.

Puoi anche limitare i risultati alla regione definita da location e da un parametro radius, aggiungendo il locationRestriction parametro. In questo modo, il completamento automatico (New) restituisce solo i risultati all'interno di questa regione.