Place Autocomplete
Mantieni tutto organizzato con le raccolte
Salva e classifica i contenuti in base alle tue preferenze.
Sviluppatori dello Spazio economico europeo (SEE)
Nota: librerie
lato server
Questa pagina descrive la libreria lato client disponibile con
l'API Maps JavaScript. Se vuoi utilizzare il
servizio web API Places sul tuo server, dai un'occhiata al
client Node.js per i servizi Google Maps. La pagina a
questo link introduce anche il client Java,
il client Python e il client Go per i servizi Google Maps.
Introduzione
Il completamento automatico è una funzionalità della libreria Places dell'API Maps JavaScript. Puoi utilizzare il completamento automatico per dare alle tue
applicazioni il comportamento di ricerca predittiva del campo di ricerca di Google Maps.
Il servizio di completamento automatico può trovare corrispondenze con parole intere e sottostringhe, risolvendo
nomi di luoghi, indirizzi e plus
code. Le applicazioni possono quindi inviare query mentre l'utente digita, per
fornire previsioni sui luoghi in tempo reale. Come definito dall'API Places,
un "luogo" può essere un'attività, una posizione geografica o un punto d'interesse
di rilievo.
Per iniziare
Prima di utilizzare la libreria Places nell'API Maps JavaScript, verifica che l'API Places sia abilitata nella console Google Cloud, nello stesso progetto configurato per l'API Maps JavaScript.
Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto che hai configurato
per l'API Maps JavaScript e fai clic su Apri.
Nell'elenco delle API nella dashboard, cerca
l'API Places.
Se vedi l'API nell'elenco, non devi fare altro. Tuttavia, questo progetto è in stato legacy.
Per saperne di più sulla fase legacy e su come eseguire la migrazione dai servizi legacy a quelli più recenti, consulta Prodotti e funzionalità legacy.
È disponibile un'eccezione per i widget Autocomplete e SearchBox, che non sono ancora disponibili come prodotto GA nell'API Places (New).
Caricare la libreria
Il servizio Places è una libreria autonoma, separata dal codice principale
dell'API Maps JavaScript. Per utilizzare le funzionalità contenute
in questa libreria, devi prima caricarla utilizzando il parametro libraries
nell'URL di bootstrap dell'API Maps:
L'API offre due tipi di widget di completamento automatico, che puoi aggiungere utilizzando rispettivamente le classi Autocomplete e SearchBox.
Inoltre, puoi utilizzare la classe AutocompleteService per recuperare
i risultati del completamento automatico in modo programmatico (consulta il riferimento dell'API Maps JavaScript:
classe AutocompleteService).
Di seguito è riportato un riepilogo delle classi disponibili:
Autocomplete aggiunge un campo di input di testo alla tua pagina web
e monitora il campo per le voci di caratteri. Man mano che l'utente inserisce il testo,
il completamento automatico restituisce le previsioni dei luoghi sotto forma di
un elenco a discesa. Quando l'utente seleziona un luogo dall'elenco, le informazioni
sul luogo vengono restituite all'oggetto di completamento automatico e possono essere recuperate
dalla tua applicazione. Vedi i dettagli di seguito.
Figura 1: campo di testo con completamento automatico ed elenco di selezioneFigura 2: modulo per l'indirizzo compilato
SearchBox aggiunge un campo di input di testo alla tua pagina web, in modo molto simile a Autocomplete. Le differenze sono le seguenti:
La differenza principale risiede nei
risultati visualizzati nell'elenco di selezione. SearchBox fornisce
un elenco esteso di previsioni, che può includere luoghi (come definiti
dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente
inserisce "pizza a new", l'elenco di selezione potrebbe includere la frase
"pizza a New York, NY" e i nomi di vari punti vendita di pizza.
SearchBox offre meno opzioni rispetto a
Autocomplete per limitare la ricerca. Nel primo caso, puoi orientare la ricerca verso un determinato LatLngBounds. In quest'ultimo caso, puoi limitare la ricerca a un paese specifico e a tipi di luoghi specifici, nonché impostare i limiti. Per ulteriori informazioni, vedi
di seguito.
Figura 3: una casella di ricerca presenta termini di ricerca e previsioni di luoghi.
Vedi i dettagli di seguito.
Puoi creare un oggetto
AutocompleteService per recuperare
le previsioni in modo programmatico. Chiama il numero getPlacePredictions() per
recuperare i luoghi corrispondenti oppure chiama il numero getQueryPredictions() per
recuperare i luoghi corrispondenti più i termini di ricerca suggeriti.
Nota: AutocompleteService non aggiunge controlli dell'interfaccia utente.
I metodi precedenti restituiscono invece un array di oggetti di previsione. Ogni
oggetto di previsione contiene il testo della previsione, nonché informazioni
di riferimento e dettagli su come il risultato corrisponde all'input dell'utente. Vedi i
dettagli di seguito.
Aggiungere un widget di completamento automatico
Il widget Autocomplete
crea un campo di input di testo nella pagina web, fornisce previsioni dei luoghi in un elenco di selezione della UI e restituisce i dettagli del luogo in risposta a una richiesta getPlace(). Ogni voce dell'elenco di selezione corrisponde a un singolo luogo (come definito dall'API Places).
Il costruttore Autocomplete accetta due argomenti:
Un elemento HTML input di tipo text. Questo è il campo di input che il servizio di completamento automatico
monitorerà e a cui allegherà i risultati.
Un argomento facoltativo AutocompleteOptions, che può
contenere le seguenti proprietà:
Un array di dati fields da includere nella
risposta Place Details per l'PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene passato ['ALL'], vengono restituiti tutti i campi disponibili e
fatturati (questa operazione non è consigliata
per le implementazioni di produzione). Per un elenco dei campi, vedi PlaceResult.
Un array di types che
specifica un tipo esplicito o una raccolta di tipi, come elencato nei tipi supportati. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi.
bounds è un oggetto google.maps.LatLngBounds che specifica
l'area in cui cercare i luoghi. I risultati sono orientati verso, ma non limitati a,
luoghi contenuti all'interno di questi limiti.
strictBounds è un boolean
che specifica se l'API deve restituire solo i luoghi che si trovano rigorosamente all'interno della regione definita
dal bounds specificato. L'API non restituisce risultati al di fuori di questa regione anche se corrispondono all'input dell'utente.
componentRestrictions può essere utilizzato per limitare i risultati a
gruppi specifici. Puoi utilizzare componentRestrictions per filtrare fino a 5
paesi. I paesi devono essere trasmessi come codice paese di due caratteri compatibile con ISO 3166-1 Alpha-2. Più paesi devono essere trasmessi come elenco di codici paese.
Nota:se ricevi risultati imprevisti con un codice paese, verifica
di utilizzare un codice che includa i paesi, i territori dipendenti e le aree speciali
di interesse geografico che intendi. Puoi trovare informazioni sui codici su
Wikipedia: List of ISO
3166 country codes o sulla piattaforma di navigazione online ISO.
placeIdOnly può essere utilizzato per indicare al widget Autocomplete di recuperare solo gli ID luogo. Se chiami
getPlace() sull'oggetto Autocomplete, l'PlaceResult
reso disponibile avrà impostate solo le proprietà place id,
types e name. Puoi utilizzare l'ID luogo restituito
con le chiamate ai servizi Places, Geocoding, Directions o Distance Matrix.
Limitare le previsioni di completamento automatico
Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luoghi, con una tendenza 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 in base al tuo caso d'uso.
Impostare le opzioni durante la costruzione
Il costruttore Autocomplete accetta un parametro AutocompleteOptions
per impostare i vincoli durante la creazione del widget. L'esempio seguente imposta le opzioni
bounds, componentRestrictions e types per richiedere luoghi di tipo establishment, privilegiando quelli all'interno dell'area geografica specificata e limitando le previsioni solo ai luoghi all'interno degli Stati Uniti. L'impostazione dell'opzione
fields specifica quali informazioni restituire sul luogo selezionato dall'utente.
Chiama setOptions() per modificare il valore di un'opzione per un widget esistente.
TypeScript
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input")asHTMLInputElement;constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
constcenter={lat:50.064192,lng:-130.605469};// Create a bounding box with sides ~10km away from the center pointconstdefaultBounds={north:center.lat+0.1,south:center.lat-0.1,east:center.lng+0.1,west:center.lng-0.1,};constinput=document.getElementById("pac-input");constoptions={bounds:defaultBounds,componentRestrictions:{country:"us"},fields:["address_components","geometry","icon","name"],strictBounds:false,};constautocomplete=newgoogle.maps.places.Autocomplete(input,options);
Specifica i campi di dati per evitare che ti vengano addebitati costi per gli SKU di dati Places non necessari. Includi la proprietà fields nell'oggetto
AutocompleteOptions passato al costruttore del widget, come mostrato nell'esempio
precedente, oppure chiama setFields() su un oggetto Autocomplete esistente.
Imposta l'opzione strictBounds per limitare i risultati ai limiti attuali, in base all'area visibile della mappa o ai limiti rettangolari.
autocomplete.setOptions({strictBounds:true});
Limitare le previsioni a un paese specifico
Utilizza l'opzione componentRestrictions o chiama il numero setComponentRestrictions() per limitare la
ricerca con completamento automatico a un insieme specifico di massimo cinque paesi.
Utilizza l'opzione types o chiama setTypes() per limitare
le previsioni a determinati tipi di luoghi. Questo vincolo specifica un tipo o una raccolta di tipi,
come elencato in Tipi di luoghi.
Se non viene specificato alcun vincolo, vengono restituiti tutti i tipi.
Per il valore dell'opzione types o il valore passato a setTypes(), puoi specificare:
Quando un utente seleziona un luogo dai suggerimenti allegati al campo di testo del completamento automatico, il servizio attiva un evento place_changed. Per ottenere i dettagli
di un luogo:
Crea un gestore di eventi per l'evento place_changed e chiama addListener()
sull'oggetto Autocomplete per aggiungere il gestore.
Chiama Autocomplete.getPlace()
sull'oggetto Autocomplete per recuperare un oggetto PlaceResult,
che puoi utilizzare per ottenere maggiori informazioni sul luogo selezionato.
Per impostazione predefinita, quando un utente seleziona un luogo, il completamento automatico restituisce tutti i campi dati disponibili per il luogo selezionato e ti verrà addebitato l'importo corrispondente.
Utilizza Autocomplete.setFields()
per specificare i campi dei dati sui luoghi da restituire. Scopri di più sull'oggetto
PlaceResult, incluso un elenco di campi di dati sui luoghi che
puoi richiedere. Per evitare di pagare per dati non necessari, assicurati di utilizzare Autocomplete.setFields() per specificare
solo i dati dei luoghi che utilizzerai.
La proprietà name contiene il
description delle previsioni di completamento automatico di Places. Per saperne di più su
description, consulta la
documentazione
di Places Autocomplete.
Per i moduli di indirizzo, è utile ottenere l'indirizzo in formato strutturato. Per restituire l'indirizzo strutturato del luogo selezionato, chiama
Autocomplete.setFields()
e specifica il campo address_components.
L'esempio seguente utilizza il completamento automatico per compilare i campi di un modulo
di indirizzo.
TypeScript
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// Get each component of the address from the place details,// and then fill-in the corresponding field on the form.// place.address_components are google.maps.GeocoderAddressComponent objects// which are documented at http://goo.gle/3l5i5Mrfor(constcomponentofplace.address_componentsasgoogle.maps.GeocoderAddressComponent[]){// @ts-ignore remove once typings fixedconstcomponentType=component.types[0];switch(componentType){case"street_number":{address1=`${component.long_name}${address1}`;break;}case"route":{address1+=component.short_name;break;}case"postal_code":{postcode=`${component.long_name}${postcode}`;break;}case"postal_code_suffix":{postcode=`${postcode}-${component.long_name}`;break;}case"locality":(document.querySelector("#locality")asHTMLInputElement).value=component.long_name;break;case"administrative_area_level_1":{(document.querySelector("#state")asHTMLInputElement).value=component.short_name;break;}case"country":(document.querySelector("#country")asHTMLInputElement).value=component.long_name;break;}}address1Field.value=address1;postalField.value=postcode;// After filling the form with address components from the Autocomplete// prediction, set cursor focus on the second address line to encourage// entry of subpremise information such as apartment, unit, or floor number.address2Field.focus();}
functionfillInAddress(){// Get the place details from the autocomplete object.constplace=autocomplete.getPlace();letaddress1="";letpostcode="";// Get each component of the address from the place details,// and then fill-in the corresponding field on the form.// place.address_components are google.maps.GeocoderAddressComponent objects// which are documented at http://goo.gle/3l5i5Mrfor(constcomponentofplace.address_components){// @ts-ignore remove once typings fixedconstcomponentType=component.types[0];switch(componentType){case"street_number":{address1=`${component.long_name}${address1}`;break;}case"route":{address1+=component.short_name;break;}case"postal_code":{postcode=`${component.long_name}${postcode}`;break;}case"postal_code_suffix":{postcode=`${postcode}-${component.long_name}`;break;}case"locality":document.querySelector("#locality").value=component.long_name;break;case"administrative_area_level_1":{document.querySelector("#state").value=component.short_name;break;}case"country":document.querySelector("#country").value=component.long_name;break;}}address1Field.value=address1;postalField.value=postcode;// After filling the form with address components from the Autocomplete// prediction, set cursor focus on the second address line to encourage// entry of subpremise information such as apartment, unit, or floor number.address2Field.focus();}window.initAutocomplete=initAutocomplete;
Per impostazione predefinita, il campo di testo creato dal servizio di completamento automatico contiene
testo segnaposto standard. Per modificare il testo, imposta l'attributo
placeholder sull'elemento input:
<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">
Nota: il testo segnaposto predefinito viene localizzato automaticamente. Se
specifichi un valore segnaposto personalizzato, devi gestire la localizzazione di questo
valore nella tua applicazione. Per informazioni su come l'API Google Maps JavaScript sceglie la lingua da utilizzare, leggi la documentazione sulla
localizzazione.
SearchBox consente agli utenti di eseguire una ricerca geografica basata su testo, ad esempio "pizza a New York" o "negozi di scarpe vicino a Robson Street".
Puoi collegare SearchBox a un campo di testo e, man mano che viene inserito il testo, il servizio restituirà le previsioni sotto forma di elenco a discesa.
SearchBox fornisce un elenco esteso di previsioni, che
possono includere luoghi (come definiti dall'API Places) e termini di ricerca
suggeriti. Ad esempio, se l'utente inserisce "pizza a new", l'elenco di selezione potrebbe
includere la frase "pizza a New York, NY" e i nomi di vari
punti vendita di pizza. Quando un utente seleziona un luogo dall'elenco,
le informazioni su quel luogo vengono restituite all'oggetto SearchBox e possono essere
recuperate dalla tua applicazione.
Il costruttore SearchBox accetta due argomenti:
Un elemento HTML input di tipo text. Questo è
il campo di input che il servizio SearchBox monitorerà e
a cui allegherà i risultati.
Un argomento options, che può contenere la proprietà bounds: bounds è un oggetto google.maps.LatLngBounds che specifica l'area in cui cercare i luoghi. I risultati
sono orientati verso, ma non limitati a, luoghi contenuti all'interno
di questi limiti.
Il seguente codice utilizza il parametro bounds per orientare i risultati
verso i luoghi all'interno di una particolare area geografica, specificata utilizzando
le coordinate di latitudine/longitudine.
Quando l'utente seleziona un elemento dai suggerimenti allegati alla casella di ricerca, il servizio attiva un evento places_changed. Puoi
chiamare getPlaces() sull'oggetto SearchBox per
recuperare un array contenente diverse previsioni, ognuna delle quali è un
oggetto PlaceResult.
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=searchBox.getPlaces();if(places.length==0){return;}// Clear out the old markers.markers.forEach((marker)=>{marker.setMap(null);});markers=[];// For each place, get the icon, name and location.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.iconasstring,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.maps.Marker({map,icon,title:place.name,position:place.geometry.location,}));if(place.geometry.viewport){// Only geocodes have viewport.bounds.union(place.geometry.viewport);}else{bounds.extend(place.geometry.location);}});map.fitBounds(bounds);});
// Listen for the event fired when the user selects a prediction and retrieve// more details for that place.searchBox.addListener("places_changed",()=>{constplaces=searchBox.getPlaces();if(places.length==0){return;}// Clear out the old markers.markers.forEach((marker)=>{marker.setMap(null);});markers=[];// For each place, get the icon, name and location.constbounds=newgoogle.maps.LatLngBounds();places.forEach((place)=>{if(!place.geometry||!place.geometry.location){console.log("Returned place contains no geometry");return;}consticon={url:place.icon,size:newgoogle.maps.Size(71,71),origin:newgoogle.maps.Point(0,0),anchor:newgoogle.maps.Point(17,34),scaledSize:newgoogle.maps.Size(25,25),};// Create a marker for each place.markers.push(newgoogle.maps.Marker({map,icon,title:place.name,position:place.geometry.location,}),);if(place.geometry.viewport){// Only geocodes have viewport.bounds.union(place.geometry.viewport);}else{bounds.extend(place.geometry.location);}});map.fitBounds(bounds);});
Recupero programmatico delle previsioni del servizio di completamento automatico dei luoghi
Per recuperare le previsioni in modo programmatico, utilizza la classe
AutocompleteService. AutocompleteService
non aggiunge controlli UI. Restituisce invece un array di oggetti di previsione, ognuno dei quali contiene il testo della previsione, informazioni di riferimento e dettagli su come il risultato corrisponde all'input dell'utente.
Questa opzione è utile se vuoi un maggiore controllo sull'interfaccia utente rispetto a quello
offerto da Autocomplete e SearchBox
descritti in precedenza.
AutocompleteService espone i seguenti metodi:
getPlacePredictions() restituisce le previsioni dei luoghi.
Nota: un "luogo" può essere un'attività, una posizione geografica o un punto d'interesse
importante, come definito dall'API Places.
getQueryPredictions() restituisce un elenco esteso di
previsioni, che possono includere luoghi (come definiti dall'API Places)
e termini di ricerca suggeriti. Ad esempio, se l'utente
inserisce "pizza a new", l'elenco di selezione potrebbe includere la frase
"pizza a New York, NY" e i nomi di vari punti vendita di pizza.
Entrambi i metodi precedenti restituiscono un array di
oggetti prediction
nel seguente formato:
description è la previsione corrispondente.
distance_meters è la distanza in metri del luogo da
AutocompletionRequest.origin specificato.
matched_substrings contiene un insieme di sottostringhe nella
descrizione che corrispondono agli elementi nell'input dell'utente. Ciò è utile per
evidenziare queste sottostringhe nella tua applicazione. In molti casi, la query
viene visualizzata come sottostringa del campo della descrizione.
length è la lunghezza della sottostringa.
offset è l'offset dei caratteri, misurato dall'inizio della stringa di descrizione, in corrispondenza del quale viene visualizzata la sottostringa corrispondente.
terms è un array contenente gli elementi della query. Per
un luogo, ogni elemento in genere costituisce una parte dell'indirizzo.
offset è l'offset dei caratteri, misurato dall'inizio della stringa di descrizione, in corrispondenza del quale viene visualizzata la sottostringa corrispondente.
value è il termine corrispondente.
L'esempio riportato di seguito esegue una richiesta di previsione di query per la frase
"pizza vicino a" e mostra il risultato in un elenco.
TypeScript
// This example retrieves autocomplete predictions programmatically from the// autocomplete service, and displays them as an HTML list.// This example requires the Places library. Include the libraries=places// parameter when you first load the API. For example:// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">functioninitService():void{constdisplaySuggestions=function(predictions:google.maps.places.QueryAutocompletePrediction[]|null,status:google.maps.places.PlacesServiceStatus){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));(document.getElementById("results")asHTMLUListElement).appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}declareglobal{interfaceWindow{initService:()=>void;}}window.initService=initService;
// This example retrieves autocomplete predictions programmatically from the// autocomplete service, and displays them as an HTML list.// This example requires the Places library. Include the libraries=places// parameter when you first load the API. For example:// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">functioninitService(){constdisplaySuggestions=function(predictions,status){if(status!=google.maps.places.PlacesServiceStatus.OK||!predictions){alert(status);return;}predictions.forEach((prediction)=>{constli=document.createElement("li");li.appendChild(document.createTextNode(prediction.description));document.getElementById("results").appendChild(li);});};constservice=newgoogle.maps.places.AutocompleteService();service.getQueryPredictions({input:"pizza near Syd"},displaySuggestions);}window.initService=initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<link rel="stylesheet" type="text/css" href="./style.css" />
<script type="module" src="./index.js"></script>
</head>
<body>
<p>Query suggestions for 'pizza near Syd':</p>
<ul id="results"></ul>
<!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
<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=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
defer
></script>
</body>
</html>
AutocompleteService.getPlacePredictions()
possono utilizzare i token di sessione (se implementati) per raggruppare le richieste di completamento automatico ai fini della fatturazione. 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 una query e termina quando seleziona un
luogo. Ogni sessione può avere più query, seguite dalla selezione di un luogo.
Una volta terminata una sessione, il token non è più valido. La tua app deve
generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per
tutte le sessioni Autocomplete. Se il parametro sessionToken viene omesso o se riutilizzi un token di sessione, la sessione viene addebitata come se non fosse stato fornito alcun token di sessione (ogni richiesta viene fatturata separatamente).
Puoi utilizzare lo stesso token di sessione per effettuare una singola richiesta
Place Details
sul luogo risultante da una chiamata a AutocompleteService.getPlacePredictions().
In questo caso, la richiesta di completamento automatico viene combinata con la richiesta Place Details e la chiamata viene addebitata come una normale richiesta Place Details. Non sono previsti costi per la
richiesta di completamento automatico.
Assicurati di trasmettere un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione Autocomplete invaliderà queste sessioni e tutte le richieste Autocomplete nelle sessioni non valide verranno addebitate singolarmente utilizzando lo SKU Autocomplete per richiesta. Scopri di più sui token di sessione.
L'esempio seguente mostra la creazione di un token di sessione, quindi il passaggio in un
AutocompleteService (la funzione displaySuggestions()
è stata omessa per brevità):
// Create a new session token.varsessionToken=newgoogle.maps.places.AutocompleteSessionToken();// Pass the token to the autocomplete service.varautocompleteService=newgoogle.maps.places.AutocompleteService();autocompleteService.getPlacePredictions({input:'pizza near Syd',sessionToken:sessionToken},displaySuggestions);
Assicurati di trasmettere un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione comporta l'addebito individuale di ogni richiesta.
Stilizzazione dei widget Completamento automatico e Casella di ricerca
Per impostazione predefinita, gli elementi della UI forniti da Autocomplete e
SearchBox sono stilizzati per l'inclusione in una mappa Google. Ti consigliamo di
modificare lo stile in base al tuo sito. Sono disponibili le seguenti classi CSS. Tutte le classi elencate di seguito si applicano sia ai widget
Autocomplete che a quelli SearchBox.
Classi CSS per i widget Autocomplete e SearchBox
Classe CSS
Descrizione
pac-container
L'elemento visivo contenente l'elenco delle previsioni restituite dal
servizio Place Autocomplete. Questo elenco viene visualizzato come elenco a discesa sotto il widget
Autocomplete o SearchBox.
pac-icon
L'icona visualizzata a sinistra di ogni elemento nell'elenco dei
pronostici.
pac-item
Un elemento nell'elenco delle previsioni fornite dal widget
Autocomplete o SearchBox.
pac-item:hover
L'elemento quando l'utente passa il puntatore del mouse sopra.
pac-item-selected
L'elemento quando l'utente lo seleziona utilizzando la tastiera. Nota: gli elementi selezionati saranno membri di questo corso e del corso pac-item.
pac-item-query
Un intervallo all'interno di un pac-item che costituisce la parte principale della
previsione. Per le località geografiche, contiene un nome di luogo, ad esempio
"Sydney", o un nome e un numero di via, ad esempio "10 King Street". Per le
ricerche basate su testo, ad esempio "pizza a New York", contiene il testo completo
della query. Per impostazione predefinita, il pac-item-query è colorato
di nero. Se nel pac-item è presente altro testo, questo si trova
al di fuori di pac-item-query e ne eredita lo stile da
pac-item. Per impostazione predefinita è colorato di grigio. Il testo aggiuntivo
è in genere un indirizzo.
pac-matched
La parte della previsione restituita che corrisponde all'input dell'utente. Per
impostazione predefinita, questo testo corrispondente viene evidenziato in grassetto. Tieni presente che il testo
corrispondente può trovarsi ovunque all'interno di pac-item. Non fa necessariamente parte di pac-item-query e potrebbe trovarsi in parte all'interno di pac-item-query e in parte nel testo rimanente in pac-item.
Ottimizzazione di Place Autocomplete (legacy)
Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio
Place Autocomplete (legacy).
Sviluppa una comprensione dei campi di dati essenziali di Place Autocomplete (legacy) fin dall'inizio.
I campi di distorsione della località 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 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 Place Autocomplete (legacy),
utilizza le maschere dei campi nei widget Place Details (legacy) e Place Autocomplete (legacy) per restituire solo i
campi dati del luogo di cui hai bisogno.
Ottimizzazione avanzata dei costi
Valuta l'implementazione programmatica di Place Autocomplete (legacy) per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding sul luogo selezionato anziché su Place Details (legacy). 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/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 (legacy).
Se gli utenti selezionano un suggerimento di completamento automatico entro una media di quattro o meno richieste di completamento automatico di Places (legacy), il prezzo per richiesta potrebbe essere più conveniente rispetto al prezzo per sessione.
Per assistenza nella scelta dell'implementazione di Place Autocomplete (legacy) 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?
Le seguenti linee guida descrivono i modi per ottimizzare il rendimento di Place Autocomplete (legacy):
Aggiungi limitazioni per paese,
priorità alla località,
e (per le implementazioni programmatiche) preferenza della lingua all'implementazione di Place Autocomplete (legacy). 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 Place Autocomplete (legacy) è accompagnato da una mappa, puoi impostare la posizione in base all'area visibile della mappa.
Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico di Places (legacy), in genere
perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input
originale dell'utente 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 Trova luogo (legacy).
Se i risultati sono previsti solo in una regione specifica, utilizza
l'aggiustamento della località.
Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
Gli utenti che inseriscono indirizzi di locali secondari, 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 Place Autocomplete (legacy).
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.
[[["Facile da capire","easyToUnderstand","thumb-up"],["Il problema è stato risolto","solvedMyProblem","thumb-up"],["Altra","otherUp","thumb-up"]],[["Mancano le informazioni di cui ho bisogno","missingTheInformationINeed","thumb-down"],["Troppo complicato/troppi passaggi","tooComplicatedTooManySteps","thumb-down"],["Obsoleti","outOfDate","thumb-down"],["Problema di traduzione","translationIssue","thumb-down"],["Problema relativo a esempi/codice","samplesCodeIssue","thumb-down"],["Altra","otherDown","thumb-down"]],["Ultimo aggiornamento 2025-10-11 UTC."],[],[]]
