Annuncio: a breve su Google Maps Platform saranno disponibili nuovi stili della mappa di base. Questo aggiornamento dello stile della mappa include una nuova tavolozza dei colori predefinita, indicatori modernizzati e miglioramenti alle esperienze e all'usabilità delle mappe. Tutti gli stili di mappa verranno aggiornati automaticamente a marzo 2025. Per ulteriori informazioni sulla disponibilità e su come attivare in anteprima questa funzionalità, consulta Nuovo stile di mappa per Google Maps Platform.
Questa pagina descrive la libreria lato client disponibile con
l'API Maps JavaScript. Se vuoi utilizzare il servizio web dell'API Places sul tuo server, dai un'occhiata al client Node.js per i servizi Google Maps. La pagina a cui rimanda il link presenta anche il client Java, il client Python e il client Go per i servizi Google Maps.
Introduzione
Il completamento automatico è una funzionalità della raccolta Places nell'API Maps JavaScript. Puoi utilizzare il completamento automatico per assegnare alle tue applicazioni il comportamento di ricerca di tipo avanzato del campo di ricerca di Google Maps.
Il servizio di completamento automatico può trovare corrispondenze per parole intere e sottostringhe, risolvendo nomi di luoghi, indirizzi e Plus Code. Le applicazioni possono quindi inviare query man mano che l'utente digita per fornire previsioni sui luoghi in tempo reale. Come definito dall'API Places,
un "luogo" può essere un esercizio, una località geografica o un punto d'interesse prominente.
Per iniziare
Prima di utilizzare la libreria Places nell'API JavaScript di Maps, assicurati innanzitutto che l'API Places sia attivata nella console Google Cloud, nello stesso progetto configurato per l'API JavaScript di Maps.
Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto configurato per l'API Maps JavaScript e fai clic su Apri.
Nell'elenco delle API nella dashboard, cerca
API Places.
Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è presente nell'elenco, attivala:
Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, nel menu a sinistra,
seleziona Raccolta.
Cerca API Places e selezionala dall'elenco dei risultati.
Seleziona ATTIVA. Al termine della procedura,
API Places viene visualizzata nell'elenco delle API nella
dashboard.
Caricamento della libreria
Il servizio Places è una libreria autosufficiente, separata dal codice principale dell'API Maps JavaScript. Per utilizzare le funzionalità contenute
all'interno di 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 rispettivamente tramite le classi Autocomplete e SearchBox.
Inoltre, puoi utilizzare la classe AutocompleteService per recuperare i risultati di completamento automatico in modo programmatico (consulta la sezione di riferimento dell'API Maps JavaScript: classe AutocompleteService).
Di seguito è riportato un riepilogo dei corsi disponibili:
Autocomplete aggiunge un campo di immissione di testo alla pagina web e monitora il campo per le inserzioni di caratteri. Man mano che l'utente inserisce il testo, il completamento automatico restituisce le previsioni dei luoghi sotto forma di elenco di opzioni 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. Consulta i dettagli di seguito.
Figura 1: campo di testo con completamento automatico ed elenco di sceltaFigura 2: modulo per l'indirizzo compilato
SearchBox aggiunge un campo di immissione di testo alla pagina web, in modo molto simile a Autocomplete. Le differenze sono le seguenti:
La differenza principale sta nei risultati visualizzati nell'elenco di scelta. 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 scelta potrebbe includere la frase "pizza a New York, NY", nonché 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. Nel
secondo caso, puoi limitare la ricerca a un determinato paese e a determinati
tipi di luoghi, nonché impostare i limiti. Per ulteriori informazioni, consulta
di seguito.
Figura 3: una casella di ricerca presenta i termini di ricerca e le previsioni dei luoghi.
Consulta i dettagli di seguito.
Puoi creare un oggetto
AutocompleteService per recuperare
le previsioni in modo programmatico. Chiama getPlacePredictions() per recuperare i luoghi corrispondenti oppure getQueryPredictions() per recuperare i luoghi corrispondenti e 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 immissione di testo nella pagina web, fornisce previsioni di luoghi in un elenco di selezione dell'interfaccia utente e restituisce i dettagli dei luoghi in risposta a una richiesta getPlace(). Ogni voce dell'elenco di scelta corrisponde a un singolo luogo (come definito dall'API Places).
Il costruttore Autocomplete accetta due argomenti:
Un elemento HTML input di tipo text. Si tratta del campo di immissione che il servizio di completamento automatico monitora e a cui allega i risultati.
Un argomento AutocompleteOptions facoltativo, che può contenere le seguenti proprietà:
Un array di dati fields da includere nella risposta Place Details per il PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene passato ['ALL'], vengono restituiti e fatturati tutti i campi disponibili (questa operazione non è consigliata per i deployment di produzione). Per un elenco dei campi, consulta 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
la zona in cui cercare i luoghi. I risultati sono orientati verso, ma non limitati a,
i luoghi contenuti all'interno di questi limiti.
strictBounds è un boolean
che specifica se l'API deve restituire solo i luoghi che si trovano strettamente all'interno della regione definita
da bounds specificato. L'API non restituisce risultati al di fuori di questa regione anche se corrispondenti all'input dell'utente.
componentRestrictions può essere utilizzato per limitare i risultati a gruppi specifici. Al momento, puoi utilizzare componentRestrictions per filtrare fino a 5 paesi. I paesi devono essere passati come codice paese compatibile ISO 3166-1 Alpha-2 di due caratteri. È necessario specificare più paesi sotto forma di 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 di interesse geografico speciale che intendi. Puoi trovare informazioni sui codici su
Wikipedia: Elenco dei codici paese ISO
3166 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, il
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, la funzionalità di completamento automatico dei luoghi presenta tutti i tipi di luoghi, con un bias per le previsioni nelle vicinanze della 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 compilazione
Il costruttore Autocomplete accetta un parametro AutocompleteOptions
per impostare i vincoli al momento della 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 le informazioni da 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 gli SKU dei dati di Places non necessari. Includi la proprietà fields in AutocompleteOptions da passare 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 correnti, 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 setComponentRestrictions() per limitare la ricerca con il completamento automatico a un insieme specifico di massimo cinque paesi.
Utilizza l'opzione types o chiama setTypes() per limitare le predizioni 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 del valore passato a setTypes(), puoi specificare:
Quando un utente seleziona un luogo dalle previsioni associate al campo di testo di completamento automatico, il servizio attiva un evento place_changed. Per visualizzare i dettagli del luogo:
Crea un gestore di eventi per l'evento place_changed e chiama addListener()
sull'oggetto Autocomplete per aggiungerlo.
Chiama Autocomplete.getPlace()
sull'oggetto Autocomplete per recuperare un oggetto PlaceResult
che potrai utilizzare per ottenere ulteriori informazioni sul luogo selezionato.
Per impostazione predefinita, quando un utente seleziona un luogo, il completamento automatico restituisce tutti i campi di dati disponibili per il luogo selezionato e ti verrà fatturato di conseguenza.
Utilizza Autocomplete.setFields() per specificare i campi di dati dei luoghi da restituire. Scopri di più sull'oggetto
PlaceResult, incluso un elenco di campi di dati dei luoghi che
puoi richiedere. Per evitare di pagare per i dati non necessari, assicurati di utilizzare Autocomplete.setFields() per specificare solo i dati dei luoghi che utilizzerai.
La proprietà name contiene il valore description delle previsioni di completamento automatico di Places. Puoi scoprire di più su description nella documentazione di Place Autocomplete.
Per i moduli di indirizzo, è utile ricevere 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 compilazione automatica contiene un 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 il tuo valore segnaposto, devi gestire la localizzazione di quel
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 "pizzeria a New York" o "negozi di scarpe vicino a Robson Street".
Puoi associare SearchBox a un campo di testo e, man mano che il testo viene inserito, il servizio restituirà le previsioni sotto forma di elenco di scelta 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 scelta può includere la frase "pizza a New York, NY", nonché 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. Si tratta del
campo di immissione che il servizio SearchBox monitorerà e a cui agganciare 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 limiti per orientare i risultati
verso i luoghi all'interno di una determinata area geografica, specificata tramite
coordinate di latitudine/longitudine.
Quando l'utente seleziona un elemento dalle previsioni associate 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);});
Recuperare in modo programmatico le previsioni del servizio Place Autocomplete
Per recuperare le previsioni in modo programmatico, utilizza la classe
AutocompleteService. AutocompleteService
non aggiunge controlli dell'interfaccia utente. Restituisce invece un array di oggetti di previsione, ciascuno contenente il testo della previsione, le informazioni di riferimento e i dettagli su come il risultato corrisponde all'input dell'utente.
Questa opzione è utile se vuoi un maggiore controllo sull'interfaccia utente rispetto a quelloofferto da Autocomplete e SearchBox descritti sopra.
AutocompleteService espone i seguenti metodi:
getPlacePredictions() restituisce le previsioni dei luoghi.
Nota: un "luogo" può essere un esercizio, una località geografica o un punto d'interesse in evidenza, 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 scelta potrebbe includere la frase "pizza a New York, NY", nonché i nomi di vari punti vendita di pizza.
Entrambi i metodi precedenti restituiscono un array di
oggetti
di previsione del seguente tipo:
description è la previsione corrispondente.
distance_meters è la distanza in metri del luogo dalAutocompletionRequest.origin specificato.
matched_substrings contiene un insieme di sottostringhe nella
descrizione che corrispondono agli elementi inseriti dall'utente. Questo è 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 cui viene visualizzata la sottostringa corrispondente.
terms è un array contenente gli elementi della query. Per un luogo, in genere ogni elemento costituisce una parte dell'indirizzo.
offset è l'offset dei caratteri, misurato dall'inizio della stringa di descrizione, in cui viene visualizzata la sottostringa corrispondente.
value è il termine corrispondente.
L'esempio seguente esegue una richiesta di previsione della query per la frase
'pizza nelle vicinanze' 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()
può utilizzare i token di sessione (se implementati) per raggruppare le richieste di completamento automatico a fini di fatturazione. I token di sessione raggruppano le fasi di query e selezione di una ricerca di completamento automatico dell'utente in una sessione distinta a fini di 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.
Al termine di una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione per tutte le sessioni di completamento automatico. Se il parametro sessionToken viene omesso o se riutilizzi un token sessione, la sessione viene addebitata come se non fosse stato fornito alcun token 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 di dettagli sul luogo e la chiamata viene addebitata come una normale richiesta di dettagli sul luogo. La richiesta di completamento automatico non comporta alcun costo.
Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione Autocomplete ne invaliderà le 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 sessione, quindi il suo 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 passare un token di sessione univoco per ogni nuova sessione. Se utilizzi lo stesso token per più di una sessione, ogni richiesta verrà fatturata singolarmente.
Aggiungere stili ai widget Completamento automatico e Casella di ricerca
Per impostazione predefinita, gli elementi dell'interfaccia utente forniti da Autocomplete e
SearchBox sono stilizzati per l'inclusione in una mappa di Google. Ti consigliamo di modificare lo stile in base alle esigenze del tuo sito. Sono disponibili le seguenti classi CSS. Tutte le classi elencate di seguito si applicano sia ai widget Autocomplete sia ai widget 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 di completamento automatico dei luoghi. Questo elenco viene visualizzato come elenco a discesa sotto il
widget Autocomplete o SearchBox.
pac-icon
L'icona visualizzata a sinistra di ogni voce nell'elenco delle predizioni.
pac-item
Un elemento nell'elenco delle previsioni fornito dal
widget Autocomplete o SearchBox.
pac-item:hover
L'elemento quando l'utente passa il mouse sopra.
pac-item-selected
L'elemento quando viene selezionato dall'utente tramite la tastiera. Nota: gli elementi selezionati
faranno parte 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 il nome di un luogo, ad esempio "Sydney", o il nome e il numero di una via, ad esempio "10 King Street". Per le ricerche basate su testo come "pizza a New York", contiene il testo completo della query. Per impostazione predefinita, il carattere pac-item-query è di colore
nero. Se pac-item contiene del testo aggiuntivo, questo text è
esterno a pac-item-query e eredita lo stile da
pac-item. È di colore grigio per impostazione predefinita. 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 è evidenziato in grassetto. Tieni presente che il testo corrispondente può trovarsi in qualsiasi punto di pac-item. Non fa necessariamente parte di pac-item-query e potrebbe essere parzialmente all'interno di pac-item-query e parzialmente nel testo rimanente di pac-item.
Ottimizzazione del completamento automatico dei luoghi
Questa sezione descrive le best practice per aiutarti a sfruttare al meglio il servizio di completamento automatico dei luoghi.
Acquisisci fin dall'inizio una conoscenza dei campi di dati di Completamento automatico dei luoghi essenziali.
I campi di bias di località e limitazione della località sono facoltativi, ma possono avere un impatto significativo sul rendimento del completamento automatico.
Utilizza la gestione degli errori per assicurarti che l'app degradi in modo corretto
se l'API restituisce un errore.
Assicurati che la tua app gestisca la situazione in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere dei campi nei widget Dettagli dei luoghi e Place Autocomplete per restituire solo i campi dati dei luoghi di cui hai bisogno.
Ottimizzazione avanzata dei costi
Valuta l'implementazione programmatica di Place Autocomplete per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details. I prezzi per richiesta abbinati all'API Geocoding sono più convenienti rispetto ai prezzi per sessione (in base alla sessione) se sono soddisfatte entrambe le seguenti condizioni:
Se ti serve solo la latitudine/longitudine o l'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore a una chiamata a Dettagli luogo.
Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro richieste di previsione di completamento automatico o meno, i prezzi per richiesta potrebbero essere più convenienti rispetto a quelli per sessione.
Per assistenza nella scelta dell'implementazione di Completamento automatico dei luoghi più adatta alle tue esigenze, seleziona la scheda corrispondente alla tua risposta alla seguente domanda.
La tua applicazione richiede altre informazioni oltre all'indirizzo e alla latitudine/longitudine della previsione selezionata?
I costi indicati qui sono in dollari statunitensi. Per informazioni complete sui prezzi, consulta la pagina Fatturazione di Google Maps Platform.
Best practice per le prestazioni
Le seguenti linee guida descrivono i modi per ottimizzare il rendimento di Ricerca automatica dei luoghi:
Aggiungi limitazioni per i paesi,
bias di località
e (per le implementazioni programmatiche) preferenze di lingua all'implementazione della funzionalità di completamento automatico dei luoghi. Con i widget non è necessaria la preferenza di lingua, poiché le preferenze di lingua vengono scelte dal browser o dal dispositivo mobile dell'utente.
Se la funzionalità di completamento automatico dei luoghi è accompagnata da una mappa, puoi modificare la posizione in base all'area visibile della mappa.
Quando un utente non sceglie una delle previsioni del completamento automatico, in genere perché nessuna di queste corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
Se prevedi che l'utente inserisca solo i dati dell'indirizzo, riutilizza i dati inseriti dall'utente
in una chiamata all'API Geocoding.
Altri scenari in cui è meglio eseguire il fallback all'API Geocoding includono:
Utenti che inseriscono indirizzi di proprietà secondarie, ad esempio indirizzi di appartamenti o unità specifiche all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha"
genera una previsione parziale in Completamento automatico dei luoghi.
Utenti che inseriscono indirizzi con prefissi di tratti stradali come "23-30 29th St, Queens" a
New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai nelle Hawaii.
[null,null,["Ultimo aggiornamento 2024-12-22 UTC."],[[["Google Maps Place Autocomplete predicts places, addresses, and plus codes as users type, similar to the Google Maps search bar."],["Autocomplete is available through UI widgets (Autocomplete, SearchBox) and programmatically via AutocompleteService."],["Developers can customize predictions using options like place types, search area, and country restrictions."],["Place Autocomplete usage is subject to billing; optimize costs by carefully selecting data fields and session management strategies."],["Programmatic requests benefit from using session tokens for billing efficiency and grouping related queries."]]],[]]
