reviews Ottieni una chiave demo di Maps: prova alcune funzionalità dell'API Maps JavaScript e di Places UI Kit senza costi con una chiave demo di Maps, senza bisogno di dati di fatturazione.
Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.
Place Autocomplete (legacy)
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, consulta la pagina Client Node.js per i servizi Google Maps. La pagina a quel link presenta anche i client Java, Python e Go per i servizi Google Maps.
Introduzione
Il completamento automatico è una funzionalità della libreria Places nell'API Maps JavaScript. Puoi utilizzare il completamento automatico per fornire alle tue applicazioni il comportamento di ricerca con previsione del testo 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 importante.
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 che hai configurato per l'API Maps JavaScript.
Fai clic sul pulsante Seleziona un progetto, quindi seleziona lo stesso progetto che hai 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. 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 (nuova).
Carica 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 bootstrap dell'API di Google 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 API Maps JavaScript: classe AutocompleteService).
Di seguito è riportato un riepilogo delle classi disponibili:
Autocomplete aggiunge un campo di immissione di testo alla tua pagina web e monitora il campo per l'inserimento di caratteri. Man mano che l'utente inserisce il testo, il completamento automatico restituisce previsioni sui luoghi sotto forma di 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. Consulta 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 immissione di testo alla 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 possono includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza a", l'elenco di selezione potrebbe includere la frase "pizza a Roma" e i nomi di varie pizzerie.
SearchBox offre meno opzioni di 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 e a tipi di luoghi specifici, oltre a impostare i limiti. Per saperne di più, consulta la sezione di seguito.
Figura 3: una SearchBox presenta termini di ricerca e 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 o chiama getQueryPredictions() per recuperare i luoghi corrispondenti più i termini di ricerca suggeriti.
Nota: AutocompleteService non aggiunge controlli UI.
I metodi sopra indicati 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. Consulta i dettagli di seguito.
Aggiungi un widget di completamento automatico
Il widget Autocomplete crea un campo di immissione di testo nella tua pagina web, fornisce previsioni dei luoghi in un elenco di selezione dell'interfaccia utente e restituisce i dettagli dei luoghi in risposta a una richiesta getPlace(). Ogni voce nell'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 immissione che il servizio di completamento automatico monitorerà e a cui allegherà i risultati.
Un argomento AutocompleteOptions facoltativo, che può contenere le seguenti proprietà:
Un array di dati fields da includere nella risposta Place Details per l'elemento PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene passato ['ALL'], vengono restituiti tutti i campi disponibili e fatturati (questa opzione 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 l'area in cui cercare i luoghi. I risultati sono orientati, ma non limitati, ai luoghi contenuti entro 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 in base a un massimo di 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 utilizzare. 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. Quando chiami
getPlace() sull'oggetto Autocomplete,
PlaceResult reso disponibile avrà solo le proprietà place id,
types e name impostate. Puoi utilizzare l'ID luogo restituito con le chiamate ai servizi Places, Geocoding, Directions o Distance Matrix.
Limita le previsioni di completamento automatico
Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luoghi, con priorità per le previsioni vicine alla posizione dell'utente, e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta le opzioni di Place Autocomplete per presentare previsioni più pertinenti in base al tuo caso d'uso.
Imposta le opzioni in fase di creazione
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, dando la priorità a quelli all'interno dell'area geografica specificata e limitando le previsioni solo ai luoghi negli Stati Uniti. Impostando l'opzione fields si specifica quali informazioni restituire in merito al 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 dei dati di Places non necessari. Includi la proprietà fields in AutocompleteOptions che viene passato al costruttore del widget, come mostrato nell'esempio precedente, o 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});
Limita le previsioni a un paese specifico
Utilizza l'opzione componentRestrictions o chiama 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 dalle previsioni associate al campo di testo di 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 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à addebitato l'importo corrispondente.
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 dati di cui non hai bisogno, assicurati di utilizzare Autocomplete.setFields() per specificare solo i dati dei luoghi che utilizzerai.
La proprietà name contiene il valore description delle previsioni di Place Autocomplete. Per saperne di più su description, consulta la documentazione di Place Autocomplete.
Per i moduli degli indirizzi, è 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 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 un valore segnaposto personalizzato, devi gestire la localizzazione di questo valore nella tua applicazione. Per informazioni su come l'API Maps JavaScript di Google sceglie la lingua da utilizzare, consulta la documentazione sulla
localizzazione.
L'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 il testo viene inserito, 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", l'elenco di selezione potrebbe includere la frase "pizza a Roma" e i nomi di varie pizzerie. 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 immissione 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, ma non limitati, ai luoghi contenuti all'interno di questi limiti.
Il seguente codice utilizza il parametro bounds per dare priorità ai risultati relativi a luoghi all'interno di una determinata area geografica, specificata utilizzando le coordinate di latitudine/longitudine.
Quando l'utente seleziona un elemento dalle previsioni allegate 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.
Per ulteriori informazioni sull'oggetto PlaceResult, consulta la documentazione sui
risultati di Place Details.
TypeScript
// 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 Place Autocomplete
Per recuperare le previsioni in modo programmatico, utilizza la classe AutocompleteService. AutocompleteService
non aggiunge alcun controllo UI. 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 quello offerto da Autocomplete e SearchBox descritti sopra.
AutocompleteService espone i seguenti metodi:
getPlacePredictions() restituisce previsioni sui 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 può includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza a", l'elenco di selezione potrebbe includere la frase "pizza a Roma" e i nomi di varie pizzerie.
Entrambi i metodi precedenti restituiscono un array di oggetti di previsione nel seguente formato:
description è la previsione corrispondente.
distance_meters è la distanza in metri del luogo dalla posizione AutocompletionRequest.origin specificata.
matched_substrings contiene un insieme di sottostringhe nella descrizione che corrispondono agli elementi nell'input dell'utente. Questo è utile per evidenziare queste sottostringhe nella tua applicazione. In molti casi, la query verrà 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, ogni elemento in genere 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 vicino" e visualizza 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 ai fini della fatturazione. I token di sessione raggruppano le fasi di query e selezione di una ricerca con completamento automatico dell'utente in una sessione distinta 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 da una selezione di luoghi.
Una volta conclusa 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 di sessione, la sessione viene addebitata come se non fosse stato fornito alcun token di sessione (ogni richiesta viene fatturata separatamente).
Devi 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 Place Details e la chiamata viene addebitata come una normale richiesta di Place Details. Non sono previsti costi per la richiesta di completamento automatico. Se non utilizzi il token di sessione per la richiesta, ti verranno addebitati i costi sia per la richiesta di completamento automatico sia per quella di Place Details.
Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione Autocomplete invaliderà le sessioni Autocomplete e tutte le richieste Autocomplete nelle sessioni non valide verranno addebitate singolarmente utilizzando lo SKU Autocomplete Per Request. Scopri di più sui token di sessione.
L'esempio seguente mostra la creazione di un token di sessione, che viene poi passato 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.
Per impostazione predefinita, gli elementi UI forniti da Autocomplete e SearchBox sono formattati per l'inclusione in una mappa Google. Potresti voler modificare lo stile in base al tuo sito. Sono disponibili le seguenti classi CSS. Tutte le classi elencate di seguito si applicano sia al widget Autocomplete sia al widget SearchBox.
Classi CSS per i widget Autocomplete e SearchBox
Classe CSS
Descrizione
pac-container
L'elemento visivo contenente l'elenco di 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 delle previsioni.
pac-item
Un elemento nell'elenco di previsioni fornito 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 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 posizioni 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 colore di pac-item-query è nero. Se è presente altro testo in pac-item, questo si trova all'esterno di pac-item-query ed eredita lo stile da pac-item. Per impostazione predefinita, è di colore 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 è 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 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 ottenere il massimo dal servizio Place Autocomplete (Legacy).
Comprendi i campi di dati essenziali di Place Autocomplete (Legacy) fin dall'inizio.
I campi di polarizzazione e limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
Utilizza la gestione degli errori per assicurarti che l'app si degradi correttamente se l'API restituisce un errore.
Assicurati che la tua app gestisca i casi in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare il costo di utilizzo del servizio Place Autocomplete (Legacy), utilizza le maschere di campo nei widget Place Details (Legacy) e Place Autocomplete (Legacy) per restituire solo i campi di dati di Place Autocomplete (Legacy) di cui hai bisogno.
Ottimizzazione avanzata dei costi
Valuta l'implementazione programmatica di Place Autocomplete (Legacy) per accedere ai prezzi di
SKU: Autocomplete - Per Request
e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details (Legacy). I prezzi per richiesta abbinati all'API Geocoding sono più convenienti dei prezzi per sessione (basati sulla sessione) se sono soddisfatte entrambe le seguenti condizioni:
Se hai bisogno solo della latitudine e della longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni a un costo inferiore rispetto a una chiamata Place Details (Legacy).
Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro o meno richieste di previsioni di Place Autocomplete (Legacy), i prezzi per richiesta possono essere più convenienti rispetto ai prezzi 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 le prestazioni di Place Autocomplete (Legacy):
Aggiungi limitazioni in base al paese, località preferita e (per le implementazioni programmatiche) preferenza sulla lingua all'implementazione di Place Autocomplete (Legacy). La preferenza sulla lingua non è necessaria con i widget, poiché questi ultimi scelgono le preferenze sulla lingua dal browser o dal dispositivo mobile dell'utente.
Se Place Autocomplete (Legacy) è accompagnato da una mappa, puoi influenzare la località in base all'area visibile della mappa.
In situazioni in cui un utente non sceglie una delle previsioni di Place Autocomplete (Legacy), in genere perché nessuna di queste previsioni è l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
Se prevedi che l'utente inserisca query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Place Details (Legacy). Se i risultati sono previsti solo in una regione specifica, utilizza la localizzazione.
Altri scenari in cui è meglio utilizzare l'API Geocoding includono:
Utenti che inseriscono indirizzi di unità secondarie, ad esempio indirizzi di unità o appartamenti specifici all'interno di un edificio. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" genera 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 alle Hawaii.
Bias di località
Per orientare i risultati verso un'area specifica, passa un parametro location e un parametro radius. In questo modo, Place Autocomplete (Legacy) preferisce mostrare i risultati
all'interno dell'area definita. Potrebbero comunque essere visualizzati risultati al di fuori dell'area definita. Puoi utilizzare il parametro includedRegionCodes per filtrare i risultati in modo da mostrare solo i luoghi all'interno di un paese specificato.
Limitazione della località
Limita i risultati a un'area specificata passando un parametro locationRestriction.
Puoi anche limitare i risultati alla regione definita da location
e da un parametro radius aggiungendo il parametro
strictbounds
. In questo modo, Place Autocomplete (Legacy) restituisce solo i risultati all'interno di quella regione.
