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 della funzionalità di completamento automatico 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 sui luoghi. Per
effettuare una richiesta di completamento automatico, chiama fetchAutocompleteSuggestions()
e trasmetti 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;
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.
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;
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;
Una sessione viene conclusa quando viene chiamato fetchFields(). Dopo aver creato l'istanza Place, non è necessario trasmettere il token di sessione a fetchFields(), poiché questa operazione viene gestita automaticamente.
await place.fetchFields({ fields: ["displayName", "formattedAddress"], });
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 Place Autocomplete.
- 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:
- Un utente inizia a digitare una query per cercare "Parigi, Francia".
- Dopo aver rilevato l'input dell'utente, l'app crea un nuovo token di sessione, "Token A".
- 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 ciascuno:
"P"
"Par"
"Parigi"
"Parigi, Francia"
- 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".
- La sessione è terminata e l'app scarta il "Token A".
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
Il seguente esempio 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
/** * Demonstrates making a single request for Place predictions, then requests Place Details for the first result. */ async function init() { // @ts-ignore 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 + '":')); for (let suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a new list element. const listItem = document.createElement('li'); const resultsElement = document.getElementById("results") as HTMLElement; 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();
JavaScript
/** * Demonstrates making a single request for Place predictions, then requests Place Details for the first result. */ async function init() { // @ts-ignore 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 + '":'), ); for (let suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a new list element. const listItem = document.createElement("li"); const resultsElement = document.getElementById("results"); 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();
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; }
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>
</head>
<body>
<div id="title"></div>
<ul id="results"></ul>
<p><span id="prediction"></span></p>
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!-- 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: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
</body>
</html>Prova campione
Digitazione predittiva di Place Autocomplete con sessioni
Questo esempio mostra la chiamata a
fetchAutocompleteSuggestions()
in base alle query dell'utente, la visualizzazione di un elenco di luoghi previsti in risposta e infine il recupero
dei dettagli del luogo selezionato. L'esempio mostra anche l'utilizzo dei token di sessione per
raggruppare una query utente con la richiesta finale di dettagli sul luogo.
TypeScript
let titleElement; let resultsContainerElement; let inputElement; let newestRequestId = 0; // Add an initial request body. const request = { input: '', 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', }; function init() { titleElement = document.getElementById('title'); resultsContainerElement = document.getElementById('results'); inputElement = document.querySelector('input'); inputElement.addEventListener('input', makeAutocompleteRequest); refreshToken(request); } async function makeAutocompleteRequest(inputEvent) { // Reset elements and exit if an empty string is received. if (inputEvent.target.value == '') { titleElement.innerText = ''; resultsContainerElement.replaceChildren(); return; } // Add the latest char sequence to the request. request.input = inputEvent.target.value; // To avoid race conditions, store the request ID and compare after the request. const requestId = ++newestRequestId; // Fetch autocomplete suggestions and show them in a list. // @ts-ignore const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request); // If the request has been superseded by a newer request, do not render the output. if (requestId !== newestRequestId) return; titleElement.innerText = `Query predictions for "${request.input}"`; // Clear the list first. resultsContainerElement.replaceChildren(); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a link for the place, add an event handler to fetch the place. const a = document.createElement('a'); a.addEventListener('click', () => { onPlaceSelected(placePrediction!.toPlace()); }); a.innerText = placePrediction!.text.toString(); // Create a new list item element. const li = document.createElement('li'); li.appendChild(a); resultsContainerElement.appendChild(li); } } // Event handler for clicking on a suggested place. async function onPlaceSelected(place) { await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); const placeText = document.createTextNode(`${place.displayName}: ${place.formattedAddress}`); resultsContainerElement.replaceChildren(placeText); titleElement.innerText = 'Selected Place:'; inputElement.value = ''; refreshToken(request); } // Helper function to refresh the session token. function refreshToken(request) { // Create a new session token and add it to the request. request.sessionToken = new google.maps.places.AutocompleteSessionToken(); } declare global { interface Window { init: () => void; } } window.init = init;
JavaScript
let titleElement; let resultsContainerElement; let inputElement; let newestRequestId = 0; // Add an initial request body. const request = { input: '', 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', }; function init() { titleElement = document.getElementById('title'); resultsContainerElement = document.getElementById('results'); inputElement = document.querySelector('input'); inputElement.addEventListener('input', makeAutocompleteRequest); refreshToken(request); } async function makeAutocompleteRequest(inputEvent) { // Reset elements and exit if an empty string is received. if (inputEvent.target.value == '') { titleElement.innerText = ''; resultsContainerElement.replaceChildren(); return; } // Add the latest char sequence to the request. request.input = inputEvent.target.value; // To avoid race conditions, store the request ID and compare after the request. const requestId = ++newestRequestId; // Fetch autocomplete suggestions and show them in a list. // @ts-ignore const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request); // If the request has been superseded by a newer request, do not render the output. if (requestId !== newestRequestId) return; titleElement.innerText = `Query predictions for "${request.input}"`; // Clear the list first. resultsContainerElement.replaceChildren(); for (const suggestion of suggestions) { const placePrediction = suggestion.placePrediction; // Create a link for the place, add an event handler to fetch the place. const a = document.createElement('a'); a.addEventListener('click', () => { onPlaceSelected(placePrediction.toPlace()); }); a.innerText = placePrediction.text.toString(); // Create a new list item element. const li = document.createElement('li'); li.appendChild(a); resultsContainerElement.appendChild(li); } } // Event handler for clicking on a suggested place. async function onPlaceSelected(place) { await place.fetchFields({ fields: ['displayName', 'formattedAddress'], }); const placeText = document.createTextNode(`${place.displayName}: ${place.formattedAddress}`); resultsContainerElement.replaceChildren(placeText); titleElement.innerText = 'Selected Place:'; inputElement.value = ''; refreshToken(request); } // Helper function to refresh the session token. function refreshToken(request) { // Create a new session token and add it to the request. request.sessionToken = new google.maps.places.AutocompleteSessionToken(); } window.init = 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; } a { cursor: pointer; text-decoration: underline; color: blue; } input { width: 300px; }
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>
</head>
<body>
<input id="input" type="text" placeholder="Search for a place..." />
<div id="title"></div>
<ul id="results"></ul>
<img
class="powered-by-google"
src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
alt="Powered by Google"
/>
<!--
The `defer` attribute causes the script to execute after the full HTML
document has been parsed. For non-blocking uses, avoiding race conditions,
and consistent behavior across browsers, consider loading using Promises. See
https://developers.google.com/maps/documentation/javascript/load-maps-js-api
for more information.
-->
<script
src="https://maps.googleapis.com/maps/api/js?key=AIzaSyA6myHzS10YXdcazAFalmXvDkrYCp5cLc8&callback=init&libraries=places&v=weekly"
defer
></script>
</body>
</html>