API Place Autocomplete Data

Sviluppatori dello Spazio economico europeo (SEE)

L'API Place Autocomplete Data ti consente di recuperare le previsioni sui luoghi in modo programmatico, per creare esperienze di completamento automatico personalizzate con un grado di controllo più preciso rispetto a quanto possibile con il widget di completamento automatico. In questa guida imparerai a utilizzare l'API Place Autocomplete Data per effettuare richieste di completamento automatico in base alle query degli utenti.

L'esempio seguente mostra un'integrazione di tipo predittivo semplificata. Inserisci la query di ricerca, ad esempio "pizza" o "poke", poi fai clic per selezionare il risultato che ti interessa.

Richieste Autocomplete

Una richiesta di completamento automatico accetta una stringa di input della query e restituisce un elenco di previsioni di luoghi. Per effettuare una richiesta di completamento automatico, chiama fetchAutocompleteSuggestions() e passa una richiesta con le proprietà necessarie. La proprietà input contiene la stringa da cercare; in un'applicazione tipica questo valore viene aggiornato man mano che l'utente digita una query. La richiesta deve includere un sessionToken, che viene utilizzato a fini di fatturazione.

Il seguente snippet mostra la creazione di un corpo della richiesta e l'aggiunta di un token di sessione, quindi la chiamata di fetchAutocompleteSuggestions() per ottenere un elenco di PlacePrediction. 

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

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 le opzioni di completamento automatico dei luoghi per presentare previsioni più pertinenti, limitando o distorcendo 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. La distorsione 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.

Utilizza la proprietà origin per specificare il punto di origine da cui calcolare la distanza geodetica dalla destinazione. Se questo valore viene omesso, la distanza non viene restituita.

Utilizza la proprietà includedPrimaryTypes per specificare fino a cinque tipi di luogo. Se non vengono specificati tipi, verranno restituiti luoghi di tutti i tipi.

Consulta il riferimento API

Ottieni i dettagli del luogo

Per restituire un oggetto Place da un risultato di previsione del luogo, chiama prima toPlace(), poi chiama fetchFields() sull'oggetto Place risultante (l'ID sessione della previsione del luogo viene incluso automaticamente). La chiamata al numero fetchFields() termina la sessione di completamento automatico. 

let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
await place.fetchFields({
    fields: ['displayName', 'formattedAddress'],
});
const placeInfo = document.getElementById('prediction');
placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
index.js

Token di sessione

I token di sessione raggruppano le fasi di query e selezione di una ricerca di completamento automatico dell'utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare. La sessione termina quando l'utente seleziona un luogo e viene effettuata una chiamata a Place Details.

Per creare un nuovo token di sessione e aggiungerlo a una richiesta, crea un'istanza di AutocompleteSessionToken, quindi imposta la proprietà sessionToken della richiesta in modo che utilizzi i token come mostrato nel seguente snippet: 

// Create a session token.
const token = new AutocompleteSessionToken();
// Add the token to the request.
// @ts-ignore
request.sessionToken = token;
index.js

Una sessione termina quando viene chiamato fetchFields(). Dopo aver creato l'istanza Place, non è necessario passare il token di sessione a fetchFields(), poiché questa operazione viene gestita automaticamente. 

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

Crea un token di sessione per la sessione successiva creando una nuova istanza di AutocompleteSessionToken.

Consigli sui token di sessione:

  • Utilizza i token di sessione per tutte le chiamate di completamento automatico dei luoghi.
  • Genera un nuovo token per ogni sessione.
  • Trasmetti un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più sessioni comporterà l'addebito individuale di ogni richiesta.

Se vuoi, puoi omettere il token di sessione Autocomplete da una richiesta. Se il token di sessione viene omesso, ogni richiesta viene fatturata separatamente, attivando lo SKU Autocomplete - Per Request. Se riutilizzi un token di sessione, la sessione viene considerata non valida e le richieste vengono addebitate come se non fosse stato fornito alcun token di sessione.

Esempio

Man mano che l'utente digita una query, viene chiamata una richiesta di completamento automatico ogni pochi caratteri (non per carattere) e viene restituito un elenco di possibili risultati. Quando l'utente effettua una selezione dall'elenco dei risultati, la selezione viene conteggiata come una richiesta e tutte le richieste effettuate durante la ricerca vengono raggruppate e conteggiate come una singola richiesta. Se l'utente seleziona un luogo, la query di ricerca è disponibile senza costi e viene addebitata solo la richiesta di dati sul luogo. Se l'utente non effettua una selezione entro pochi minuti dall'inizio della sessione, viene addebitata solo la query di ricerca.

Dal punto di vista di un'app, il flusso di eventi è il seguente:

  1. Un utente inizia a digitare una query per cercare "Parigi, Francia".
  2. Dopo aver rilevato l'input dell'utente, l'app crea un nuovo token di sessione, "Token A".
  3. Man mano che l'utente digita, l'API effettua una richiesta di completamento automatico ogni pochi caratteri, visualizzando un nuovo elenco di potenziali risultati per ciascuna:
    "P"
    "Par"
    "Parigi"
    "Parigi, Francia"
  4. Quando l'utente effettua una selezione:
    • Tutte le richieste risultanti dalla query vengono raggruppate e aggiunte alla sessione rappresentata da "Token A" come singola richiesta.
    • La selezione dell'utente viene conteggiata come richiesta Place Details e aggiunta alla sessione rappresentata da "Token A".
  5. La sessione termina e l'app scarta il "Token A".
Scopri di più su come vengono fatturate le sessioni

Codice di esempio completo

Questa sezione contiene esempi completi che mostrano come utilizzare l'API Place Autocomplete Data .

Previsioni di completamento automatico di Place Autocomplete

L'esempio seguente mostra la chiamata a fetchAutocompleteSuggestions() per l'input "Tadi", quindi la chiamata a toPlace() sul primo risultato di previsione, seguita da una chiamata a fetchFields() per ottenere i dettagli del luogo.

TypeScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } =
        (await google.maps.importLibrary(
            'places'
        )) as google.maps.PlacesLibrary;

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

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

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

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

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

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

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

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

    const placeInfo = document.getElementById('prediction') as HTMLElement;
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}

init();
index.ts

JavaScript

async function init() {
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = (await google.maps.importLibrary('places'));
    // Add an initial request body.
    let request = {
        input: 'Tadi',
        locationRestriction: {
            west: -122.44,
            north: 37.8,
            east: -122.39,
            south: 37.78,
        },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ['restaurant'],
        language: 'en-US',
        region: 'us',
    };
    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
    const title = document.getElementById('title');
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));
    const resultsElement = document.getElementById('results');
    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;
        // Create a new list element.
        const listItem = document.createElement('li');
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }
    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    const placeInfo = document.getElementById('prediction');
    placeInfo.textContent = `First predicted place: ${place.displayName}: ${place.formattedAddress}`;
}
init();
index.js

CSS

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

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

style.css

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <div id="title"></div>
        <ul id="results"></ul>
        <p><span id="prediction"></span></p>
        <img
            class="powered-by-google"
            src="./powered_by_google_on_white.png"
            alt="Powered by Google" />
    </body>
</html>
index.html

Prova campione

Digitazione predittiva con completamento automatico dei luoghi e sessioni

Questo esempio illustra i seguenti concetti:

  • Chiamata fetchAutocompleteSuggestions() in base alle query degli utenti e che mostra un elenco di luoghi previsti in risposta.
  • Utilizzo dei token di sessione per raggruppare una query utente con la richiesta Place Details finale.
  • Recupero dei dettagli del luogo selezionato e visualizzazione di un indicatore.
  • Utilizzo dell'inserimento dei controlli per nidificare gli elementi dell'interfaccia utente nell'elemento gmp-map.

TypeScript

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

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

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

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

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

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

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

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

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

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

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

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

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

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

        if (!placePrediction) {
            continue;
        }

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

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

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

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

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

    await refreshToken();

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

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

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

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

    // Increment the token counter.
    tokenCount++;

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

init();
index.ts

JavaScript

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

CSS

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

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

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

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

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

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

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

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

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

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

style.css

HTML

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

        <link rel="stylesheet" type="text/css" href="./style.css" />
        <script type="module" src="./index.js"></script>
        <!-- prettier-ignore -->
        <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8", v: "weekly"});</script>
    </head>
    <body>
        <gmp-map center="37.7893, -122.4039" zoom="12" map-id="DEMO_MAP_ID">
            <div class="controls" slot="control-inline-start-block-start">
                <input
                    type="text"
                    class="input"
                    placeholder="Search for a place..."
                    autocomplete="off" /><!-- Turn off the input's own autocomplete (not supported by all browsers).-->
                <div class="token-status"></div>
                <div class="title"></div>
                <ol class="results"></ol>
            </div>
        </gmp-map>
    </body>
</html>
index.html

Prova campione

Ottimizzazione del completamento automatico (novità)

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 per il completamento automatico (novità) fin dall'inizio.
  • I campi di preferenza della località e di limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che la tua app funzioni correttamente se l'API restituisce un errore.
  • Assicurati che la tua app gestisca i casi in cui non è presente alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione di base dei costi

Per ottimizzare il costo dell'utilizzo del servizio Autocomplete (New), utilizza le maschere dei campi 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 sul luogo selezionato anziché su Places Details (New). Il prezzo per richiesta abbinato all'API Geocoding è più conveniente del prezzo per sessione (basato sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:

  • Se hai bisogno solo della latitudine/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 un suggerimento di completamento automatico entro una media di quattro o meno richieste di completamento automatico (nuovo), il prezzo per richiesta potrebbe essere più conveniente rispetto al prezzo per sessione.
Per assistenza nella selezione dell'implementazione di Completamento automatico (nuovo) 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ì, sono necessari ulteriori dettagli

Utilizza Autocomplete basato sulla sessione (novità) con Place Details (novità).
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 (a livello di programmazione o integrato nei widget JavaScript, Android o iOS) per sessione più gli SKU Places applicabili, a seconda dei campi di dati del luogo che richiedi.1

Implementazione del 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) nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi di dati di completamento automatico (nuovo) di cui hai bisogno.

Implementazione programmatica
Utilizza un token di sessione con le richieste Autocomplete (New). Quando richiedi Place Details (New) sulla previsione selezionata, includi i seguenti parametri:

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

No, servono solo l'indirizzo e la posizione

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 (nuovo) di ogni applicazione varia a seconda di ciò che inseriscono gli utenti, 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 digitati da un utente prima di selezionare una previsione di completamento automatico (nuovo) nella tua applicazione.

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

Sì

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

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con ancora meno caratteri.

No

Utilizza Autocomplete basato sulla sessione (novità) con Place Details (novità).
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 Autocomplete (New) sia per la richiesta Places Details (New) associata per sessione. 1

Implementazione del widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android, o iOS. Sono incluse sia le richieste Autocomplete (New) sia le richieste Place Details (New) nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi necessari.

Implementazione programmatica
Utilizza un token di sessione con le richieste Autocomplete (New). Quando richiedi i dettagli del luogo (nuovo) sulla previsione selezionata, includi i seguenti parametri:

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

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

Se il ritardo delle richieste può portare la tua richiesta programmatica media al di sotto di quattro, puoi seguire le indicazioni per l'implementazione dell'autocomplete performante (nuovo) con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere previsioni a ogni nuovo tasto premuto.

Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano 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 il rendimento del completamento automatico (nuovo):

  • Aggiungi limitazioni per paese, bias di località, e (per le implementazioni programmatiche) preferenza della lingua all'implementazione di Completamento automatico (nuovo). La preferenza della lingua non è necessaria con i widget, poiché questi scelgono le preferenze della lingua dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico (nuovo) è accompagnato da una mappa, puoi impostare la località in base alla visualizzazione della mappa.
  • Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico (nuovo), 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 Dettagli luogo (nuovo). Se i risultati sono previsti solo in una regione specifica, utilizza la priorità della località.
    Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
    • Gli 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, Praha" restituisce una previsione parziale in Autocomplete (New).
    • Gli 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 nelle Hawaii.

Bias di località

Inclina i risultati verso un'area specificata passando un parametro location e un parametro radius. In questo modo, il completamento automatico (nuovo) 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 components per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specifico.

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.