Widget di completamento automatico dei luoghi

Sviluppatori dello Spazio economico europeo (SEE)

Il widget Place Autocomplete crea un campo di immissione di testo, fornisce previsioni sui luoghi in un elenco di selezione dell'interfaccia utente e restituisce i dettagli dei luoghi 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 API completo, consulta PlaceAutocompleteElement.

Prerequisiti

Per utilizzare Place Autocomplete, devi abilitare l'API Places (nuova) nel tuo progetto Google Cloud. Per maggiori dettagli, consulta Inizia.

Novità

Place Autocomplete è stato migliorato nei seguenti modi:

  • La UI del widget Autocomplete supporta la localizzazione regionale (incluse le lingue con scrittura da destra a sinistra) per il segnaposto di inserimento del testo, il logo dell'elenco delle previsioni e le previsioni dei luoghi.
  • Accessibilità migliorata, incluso il supporto per screen reader e l'interazione con la tastiera.
  • Il widget Autocomplete restituisce la nuova classe Place (riferimento Place) per semplificare la gestione dell'oggetto restituito.
  • Migliore supporto per dispositivi mobili e schermi di piccole dimensioni.
  • Prestazioni migliori e aspetto grafico migliorato.

Aggiungi un widget di completamento automatico

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

Aggiungi un widget di completamento automatico a una pagina web

Per aggiungere il widget Autocomplete 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

Aggiungi un widget Autocomplete a una mappa

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

Per aggiungere un widget Autocomplete a una mappa, richiedi innanzitutto 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 elemento gmp-place-autocomplete all'interno di un elemento div e nidifica l'elemento div all'interno di un elemento 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 in modo programmatico un widget di completamento automatico a una mappa, crea una nuova istanza google.maps.places.PlaceAutocompleteElement, aggiungi PlaceAutocompleteElement a un div e applica l'attributo slot a 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

Aggiungi testo segnaposto

Utilizza la proprietà placeholder per aggiungere testo segnaposto. L'esempio seguente mostra l'impostazione del 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...';

Limita le previsioni di completamento automatico

Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luoghi, con una preferenza per le previsioni vicine 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 Autocomplete ignori tutti i risultati che si trovano al di fuori dell'area di limitazione. Una pratica comune è limitare i risultati ai limiti della mappa. La polarizzazione dei risultati fa sì che il widget Autocomplete mostri i risultati all'interno dell'area specificata, ma alcune corrispondenze potrebbero trovarsi al di fuori di quell'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 darà la priorità ai risultati relativi a quella posizione. Imposta i limiti ogni volta che è 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 impostata tramite la panoramica o lo zoom sulla mappa, oppure un'area visibile impostata dallo sviluppatore in base alla posizione e al raggio del dispositivo. Se non è disponibile un raggio, 5 km è considerato un valore predefinito ragionevole per Place Autocomplete. Non impostare un'area visibile con raggio pari a zero (un singolo punto), un'area visibile di pochi metri (meno di 100 metri) o un'area visibile che copre l'intero globo.

Limita la ricerca di luoghi in base al paese

Per limitare la ricerca di luoghi a uno o più paesi specifici, utilizza la proprietà includedRegionCodes 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'];;

Limita la ricerca di luoghi ai limiti della mappa

Per limitare la ricerca dei luoghi ai limiti di una mappa, utilizza la proprietà locationRestriction. Il seguente snippet 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, impostala su null.

Risultati di ricerca di luoghi con bias

Per orientare i risultati di ricerca dei luoghi verso un'area circolare, utilizza la proprietà locationBias, come mostrato di seguito:

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

Per rimuovere locationBias, impostala su null.

Limita i risultati di ricerca dei luoghi a determinati tipi

Limita i risultati di ricerca dei luoghi a determinati tipi di luoghi utilizzando la proprietà includedPrimaryTypes 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 dei tipi di luoghi A e B.

Ottieni i dettagli del luogo

Per ottenere i dettagli di un luogo selezionato, aggiungi un listener gmp-select 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 (riferimento Place). Chiama place.fetchFields() per ottenere i campi di dati di Place Details necessari per la tua applicazione.

Il listener nell'esempio seguente 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 delle mappe di esempio presenti in questa pagina.

Elemento Autocomplete

Questo esempio aggiunge un widget Autocomplete 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 con completamento automatico

Questo esempio mostra come aggiungere un widget Autocomplete 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 (nuovo)

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

Ecco alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico (nuovo) dell'API Maps JavaScript, il widget di completamento automatico (nuovo) di Places SDK for Android o il widget di completamento automatico (nuovo) di Places SDK for iOS.
  • Comprendi i campi di dati essenziali di Autocomplete (New) fin dall'inizio.
  • I campi di polarizzazione e limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che l'app si degradi correttamente 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 di utilizzo del servizio Autocomplete (New), utilizza le maschere di campo nei widget Place Details (New) e Autocomplete (New) per restituire solo i campi di dati di Autocomplete (New) di cui hai bisogno.

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica di Autocomplete (New) per accedere allo SKU: Autocomplete Request pricing e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details (New). I prezzi per richiesta abbinati all'API Geocoding sono più convenienti dei prezzi per sessione (basati sulla sessione) se sono 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 di Place Details (New).
  • Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di completamento automatico (nuovo), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi per sessione.
Per scegliere l'implementazione di Autocomplete (New) più economica per la tua applicazione, individua nella tabella seguente la riga corrispondente alle esigenze della tua applicazione.
Cosa serve per la tua richiesta Numero medio di richieste di completamento automatico (nuovo) prima che un utente selezioni una previsione Implementazione consigliata
Place Details diversi dall'indirizzo e dalla posizione, ad esempio il nome del luogo, lo stato dell'attività o l'orario di apertura Qualsiasi numero Autocomplete (New) basato su sessione con Place Details (New)
Solo l'indirizzo e la latitudine/longitudine della previsione selezionata Quattro o meno Completamento automatico (nuovo) per richiesta con l'API Geocoding
Solo l'indirizzo e la latitudine/longitudine della previsione selezionata Più di quattro Autocomplete (New) basato su sessione per applicazioni solo per indirizzi

L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details (New) per la tua applicazione, a seconda delle prestazioni di utilizzo di Autocomplete (New). L'efficienza di Autocomplete (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 delle prestazioni.

Per trovare il numero medio di richieste per la tabella, analizza quanti caratteri un utente digita in media prima di selezionare una previsione di Autocomplete (New) nella tua applicazione.

Autocomplete (New) basato su sessione con Place Details (New)

Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché la tua applicazione richiede Place Details (New), come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Autocomplete (New) deve utilizzare un token di sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per sessione, oltre agli SKU di Places applicabili, a seconda dei campi di dati dei luoghi richiesti.1

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) sulla previsione selezionata. Assicurati di specificare il parametro fields per richiedere solo i campi di dati di Autocomplete (New) di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le tue richieste Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:

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

Autocomplete (New) per richiesta con l'API Geocoding

Implementa Autocomplete (New) in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione di luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine. L'esecuzione di quattro richieste Autocomplete Requests più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è inferiore al costo per sessione di Autocomplete (New).1

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero ancora minore di caratteri.

Autocomplete (New) basato su sessione per applicazioni solo per indirizzi

Utilizza Autocomplete (New) basato su sessione con Place Details (New).
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Autocomplete (New) supera il costo dei prezzi per sessione, la tua implementazione di Autocomplete (New) deve utilizzare un token di sessione sia per le richieste di Autocomplete (New) sia per la richiesta Place Details (New) associata per sessione. 1

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Autocomplete (New) sia la richiesta Place Details (New) 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 Autocomplete (New). Quando richiedi i dettagli dei luoghi (nuova versione) relativi alla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta di Autocomplete (New)
  2. Il token di sessione utilizzato nella richiesta Autocomplete (New)
  3. Il parametro fields che specifica i campi, ad esempio indirizzo e geometria

Valuta la possibilità di ritardare le richieste di Autocomplete (New)
Puoi adottare strategie come ritardare una richiesta di Autocomplete (New) finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, se effettui richieste di Autocomplete (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 API Geocoding, il costo totale sarà di 4 richieste Autocomplete (New) Per Request + Geocoding.1

Se ritardando le richieste puoi ridurre la media delle richieste programmatiche a meno di quattro, puoi seguire le indicazioni per l'implementazione di Autocomplete (New) con l'API Geocoding. 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 adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che stanno cercando con meno caratteri.

  1. Per i costi, consulta i listini prezzi di Google Maps Platform.

Best practice per le prestazioni

Le seguenti linee guida descrivono i modi per ottimizzare le prestazioni di Autocomplete (New):

  • Aggiungi limitazioni in base al paese, localizzazione e (per le implementazioni programmatiche) preferenza sulla lingua alla tua implementazione di Autocomplete (New). La preferenza sulla lingua non è necessaria con i widget, poiché questi ultimi scelgono le preferenze sulla lingua dal browser o dal dispositivo mobile dell'utente.
  • Se Autocomplete (New) è accompagnato da una mappa, puoi influenzare la località in base all'area visibile della mappa.
  • In situazioni in cui un utente non sceglie una delle previsioni di Autocomplete (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 in base al nome o all'indirizzo, utilizza una richiesta Place Details (New). Se i risultati sono previsti solo in una regione specifica, utilizza la localizzazione.
    Altri scenari in cui è meglio utilizzare l'API Geocoding includono:
    • Utenti che inseriscono indirizzi di unità secondarie, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" restituisce una previsione parziale in Autocomplete (New).
    • Utenti che inseriscono indirizzi con prefissi di segmenti stradali come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.

Bias di località

Per orientare i risultati verso un'area specifica, passa un parametro location e un parametro radius. In questo modo, Autocomplete (New) preferisce mostrare i risultati all'interno dell'area definita. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.

Limitazione della località

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 parametro locationRestriction . In questo modo, Autocomplete (New) restituisce solo i risultati all'interno di quella regione.