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, consulta il Client Node.js per i servizi Google Maps. La pagina con
questo link presenta anche il client Java,
il client Python e il client Go per Google Maps Services.
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 digitazione del campo di ricerca di Google Maps.
Il servizio di completamento automatico può corrispondere a parole e sottostringhe complete, risolvendo toponili, indirizzi e plus code. Le applicazioni possono quindi inviare query come tipi di utente per fornire previsioni immediate sui luoghi.
Come iniziare
Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati
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 scegli lo stesso progetto che hai impostato per l'API Maps JavaScript e fai clic su Apri.
Nell'elenco delle API nella Dashboard, cerca
Places API.
Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala:
Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, dal menu a sinistra, seleziona Raccolta.
Cerca l'API Places e selezionala dall'elenco dei risultati.
Seleziona ABILITA. Al termine della procedura, l'API Places viene visualizzata nell'elenco delle API nella dashboard.
Caricamento della raccolta in corso...
Il servizio Places è una libreria autonoma, separata dal codice principale dell'API Maps JavaScript. Per utilizzare la funzionalità contenuta in questa libreria, devi innanzitutto 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 rispettivamente tramite
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 di Maps JavaScript:
Classe AutocompleteService).
Ecco un riepilogo dei corsi disponibili:
Autocomplete aggiunge un campo di immissione di testo alla tua pagina web
e monitora tale campo per verificare l'inserimento di caratteri. Man mano che l'utente inserisce il testo, il completamento automatico restituisce le previsioni dei luoghi sotto forma di elenco a discesa. Quando l'utente seleziona un luogo dall'elenco, le informazioni relative al luogo vengono restituite all'oggetto del completamento automatico e possono essere recuperate dall'applicazione. Consulta i dettagli di seguito.
Figura 1: campo di testo del completamento automatico e elenco di selezioneFigura 2: modulo di indirizzo compilato
SearchBox aggiunge un campo di immissione di testo alla tua pagina web, proprio come
Autocomplete. Le differenze sono le seguenti:
La differenza principale sta nei risultati visualizzati nell'elenco di selezione. SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) più termini di ricerca suggeriti. Ad esempio, se l'utente
inserisce "pizza in nuovo", l'elenco di suggerimenti potrebbe includere la frase
"pizza a New York, NY" oltre ai nomi di vari punti
di pizza.
SearchBox offre meno opzioni rispetto a Autocomplete per limitare la ricerca. Nel primo caso, puoi
polarizzare la ricerca verso un determinato LatLngBounds. Nell'ultima opzione, puoi limitare la ricerca a un determinato paese e a particolari tipi di luogo, oltre a impostare i limiti. Per saperne di più, consulta
sotto.
Figura 3: una casella di ricerca presenta i termini di ricerca e le previsioni dei 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 o chiama getQueryPredictions() per
recuperare i luoghi corrispondenti più i termini di ricerca suggeriti.
Nota: AutocompleteService non aggiunge alcun controllo UI.
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 sul modo in cui il risultato corrisponde all'input utente. Consulta i dettagli di seguito.
Aggiungere un widget di completamento automatico
Il widget Autocomplete crea un campo di immissione di testo sulla tua pagina web, fornisce previsioni sui luoghi in un elenco di selezione UI e restituisce i dettagli del luogo 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 verrà controllato dal servizio di completamento automatico e a cui associa 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 valore PlaceResult selezionato dall'utente. Se la
proprietà non è impostata o se viene trasmesso ['ALL'], tutti i campi disponibili vengono restituiti e
fatturati (opzione sconsigliata per i deployment di produzione). Per un elenco dei campi, consulta la sezione 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, verranno 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 all'interno di questi limiti.
strictBounds specifica un boolean
specificando 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 utente.
componentRestrictions può essere utilizzato per limitare i risultati a gruppi specifici. Al momento, puoi utilizzare componentRestrictions per filtrare in base a un massimo di cinque paesi. I paesi devono essere trasmessi come codice paese compatibile con ISO 3166-1 Alpha-2 a due caratteri. Più paesi devono essere trasmessi come elenco di codici paese.
placeIdOnly può essere utilizzato per fornire al widget Autocomplete l'istruzione di recuperare solo gli ID luogo. Durante la chiamata a
getPlace() sull'oggetto Autocomplete, PlaceResult ha reso disponibili solo le proprietà place id,
types e name. Puoi utilizzare l'ID luogo restituito con chiamate ai servizi Places, Geocoding, Directions o Distance Matrix.
Previsioni di completamento automatico vincolanti
Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luogo, polarizzati per le previsioni vicino alla località dell'utente e recupera tutti i campi di dati disponibili per la posizione selezionata dall'utente. Imposta le opzioni di completamento automatico del luogo per presentare previsioni più pertinenti in base al tuo caso d'uso.
Imposta opzioni in fase di costruzione
Il costruttore Autocomplete accetta un parametro AutocompleteOptions per impostare dei vincoli al momento della creazione del widget. L'esempio seguente imposta le opzioni
bounds, componentRestrictions e types per
richiedere luoghi di tipo establishment, favorendo quelli all'interno dell'area geografica specificata
e limitando le previsioni solo alle località all'interno degli Stati Uniti. L'impostazione dell'opzione
fields consente di specificare quali informazioni restituire in merito al luogo selezionato dell'utente.
Richiama setOptions() per modificare il valore di un'opzione per un widget esistente.
TypeScript
const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
north: center.lat + 0.1,
south: center.lat - 0.1,
east: center.lng + 0.1,
west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
bounds: defaultBounds,
componentRestrictions: { country: "us" },
fields: ["address_components", "geometry", "icon", "name"],
strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);
Specifica i campi dei dati per evitare che ti vengano addebitati SKU di dati sui luoghi che non ti servono. Includi la proprietà fields in AutocompleteOptions che vengono passati 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 });
Limita le previsioni a un paese specifico
Utilizza l'opzione componentRestrictions o chiama setComponentRestrictions() per limitare la ricerca con completamento automatico a un gruppo specifico di massimo cinque paesi.
Usa 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 collegate al campo di testo del 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 richiama 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à addebitata la cifra 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 dei dati dei luoghi che puoi richiedere. Per evitare di pagare dati che non ti servono, assicurati di utilizzare Autocomplete.setFields() per specificare
solo i dati del luogo che utilizzerai.
Per i moduli di indirizzo è utile ottenere l'indirizzo in formato strutturato. Per
restituire l'indirizzo strutturato per il luogo selezionato, chiama
Autocomplete.setFields()
e specifica il campo address_components.
L'esempio seguente utilizza il completamento automatico per compilare i campi in un modulo.
TypeScript
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// 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/3l5i5Mr
for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
// @ts-ignore remove once typings fixed
const componentType = 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") as HTMLInputElement).value =
component.long_name;
break;
case "administrative_area_level_1": {
(document.querySelector("#state") as HTMLInputElement).value =
component.short_name;
break;
}
case "country":
(document.querySelector("#country") as HTMLInputElement).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();
}
function fillInAddress() {
// Get the place details from the autocomplete object.
const place = autocomplete.getPlace();
let address1 = "";
let postcode = "";
// 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/3l5i5Mr
for (const component of place.address_components) {
// @ts-ignore remove once typings fixed
const componentType = 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 nell'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 gestirne la localizzazione nell'applicazione. Per informazioni su come l'API JavaScript di Google Maps sceglie la lingua da utilizzare, leggi la documentazione sulla
localizzazione.
SearchBox consente agli utenti di eseguire una ricerca geografica
basata su testo, come "pizza a Roma" o "negozi di scarpe vicino a milano".
Puoi collegare SearchBox a un campo di testo e, quando viene inserito il testo, il servizio restituirà previsioni sotto forma di elenco a discesa.
SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) più termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuovo", l'elenco di elementi scelti può includere la frase "pizza a Roma, Roma" e i nomi di diversi locali di pizza. Quando un utente seleziona un luogo dall'elenco, le informazioni relative a tale luogo vengono restituite all'oggetto SearchBox e possono essere recuperate dall'applicazione.
Il costruttore SearchBox accetta due argomenti:
Un elemento HTML input di tipo text. Questo è il campo di immissione che verrà controllato dal servizio SearchBox e a cui collegherà 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 codice che segue utilizza il parametro bounds per sbiecare i risultati in base ai luoghi all'interno di una determinata area geografica, specificate tramite le coordinate di latitudine/longitudine.
var defaultBounds = new google.maps.LatLngBounds(
new google.maps.LatLng(-33.8902, 151.1759),
new google.maps.LatLng(-33.8474, 151.2631));
var input = document.getElementById('searchTextField');
var searchBox = new google.maps.places.SearchBox(input, {
bounds: defaultBounds
});
Modificare l'area di ricerca per SearchBox
Per modificare l'area di ricerca per un elemento SearchBox esistente, chiama
setBounds() nell'oggetto SearchBox e passa l'oggetto
LatLngBounds pertinente.
Quando l'utente seleziona un elemento dalle previsioni allegate alla casella di
ricerca, il servizio attiva un evento places_changed. Puoi
chiamare getPlaces() nell'oggetto SearchBox, per
recuperare un array contenente diverse previsioni, ciascuna 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", () => {
const places = 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.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon as string,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.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", () => {
const places = 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.
const bounds = new google.maps.LatLngBounds();
places.forEach((place) => {
if (!place.geometry || !place.geometry.location) {
console.log("Returned place contains no geometry");
return;
}
const icon = {
url: place.icon,
size: new google.maps.Size(71, 71),
origin: new google.maps.Point(0, 0),
anchor: new google.maps.Point(17, 34),
scaledSize: new google.maps.Size(25, 25),
};
// Create a marker for each place.
markers.push(
new google.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 dei luoghi del completamento automatico del servizio
Per recuperare le previsioni in modo programmatico, utilizza la classe AutocompleteService. AutocompleteService
non aggiunge controlli UI. Restituisce invece una matrice di oggetti di previsione, ciascuno contenente il testo della previsione, le informazioni di riferimento e i dettagli di come il risultato corrisponde all'input utente.
Questo è utile se vuoi avere un maggiore controllo sull'interfaccia utente rispetto a quanto offerto da Autocomplete e SearchBox descritti in precedenza.
AutocompleteService espone i seguenti metodi:
getPlacePredictions() restituisce le previsioni del luogo.
Nota: un "luogo" può essere un'organizzazione, una posizione geografica o un punto d'interesse di spicco, come definito dall'API Places.
getQueryPredictions() restituisce un elenco esteso di
previsioni, che possono includere luoghi (come definiti dall'API Places)
oltre ai termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuovo", l'elenco di elementi scelti può includere la frase "pizza a Roma, Roma" e i nomi di diversi punti ristoro.
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 dal valore AutocompletionRequest.origin specificato.
matched_substrings contiene un insieme di sottostringhe
nella descrizione che corrispondono agli elementi nell'input dell'utente. È utile per evidenziare queste sottostringhe nella tua applicazione. In molti casi, la query viene visualizzata come sottostringa del campo Descrizione.
length è la lunghezza della sottostringa.
offset è l'offset di caratteri, misurato dall'inizio della stringa di descrizione, in cui compare la sottostringa corrispondente.
terms è un array contenente elementi della query. In
un luogo, in genere ogni elemento costituisce una parte dell'indirizzo.
offset è l'offset di caratteri, misurato dall'inizio della stringa di descrizione, in cui compare la sottostringa corrispondente.
value è il termine corrispondente.
L'esempio seguente esegue una richiesta di previsione della query per la frase "pizza vicino" 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">
function initService(): void {
const displaySuggestions = 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) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
(document.getElementById("results") as HTMLUListElement).appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
declare global {
interface Window {
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">
function initService() {
const displaySuggestions = function (predictions, status) {
if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
alert(status);
return;
}
predictions.forEach((prediction) => {
const li = document.createElement("li");
li.appendChild(document.createTextNode(prediction.description));
document.getElementById("results").appendChild(li);
});
};
const service = new google.maps.places.AutocompleteService();
service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}
window.initService = initService;
<html>
<head>
<title>Retrieving Autocomplete Predictions</title>
<script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>
<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 callback 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() utilizza i token di sessione per raggruppare le richieste di completamento automatico a scopo di fatturazione. I token di sessione raggruppano le fasi di query e selezione di una ricerca dell'utente con completamento automatico 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 da una selezione di luoghi.
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 con completamento automatico. Se il parametro sessionToken viene omesso o se riutilizzi un token di sessione, l'addebito viene effettuato 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 Dettagli luogo per il luogo risultante da una chiamata a AutocompleteService.getPlacePredictions().
In questo caso, la richiesta di completamento automatico viene combinata con la richiesta Dettagli luogo e la chiamata viene addebitata come una normale richiesta Dettagli luogo. Non è previsto alcun costo per la richiesta di completamento automatico.
Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione di completamento automatico invaliderà tali sessioni e tutte le richieste di completamento automatico nelle sessioni non valide verranno addebitate individualmente utilizzando lo SKU di completamento automatico per richiesta. Scopri di più sui token di sessione.
L'esempio seguente mostra la creazione di un token di sessione e il suo trasferimento in un
AutocompleteService (la funzione displaySuggestions()
è stata omessa per brevità):
// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();
// Pass the token to the autocomplete service.
var autocompleteService = new google.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 individualmente.
Per impostazione predefinita, gli elementi UI forniti da Autocomplete e
SearchBox hanno uno stile per l'inclusione in una mappa di Google. Ti consigliamo di modificare lo stile per adattarlo 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
lezione 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
previsioni.
pac-item
Una voce nell'elenco delle previsioni fornite dal widget Autocomplete o SearchBox.
pac-item:hover
L'elemento su cui l'utente ci passa sopra con il puntatore del mouse.
pac-item-selected
L'elemento quando l'utente lo seleziona tramite la tastiera. Nota: gli elementi selezionati saranno membri di questa classe e della classe 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 un nome di luogo, come "Sydney", o un nome e un numero civico, come "10 King Street". Per le ricerche basate su testo come "pizza a Roma", contiene il testo completo della query. Per impostazione predefinita, il colore di pac-item-query
è nero. Se è presente testo aggiuntivo in pac-item, è
esterno a 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, il testo corrispondente è evidenziato in grassetto. Tieni presente che il testo corrispondente potrebbe essere in qualsiasi punto all'interno di pac-item. Non fa necessariamente parte di pac-item-query e potrebbe essere in parte all'interno di pac-item-query e in parte nel testo rimanente in pac-item.
Effettua l'ottimizzazione del completamento automatico
Questa sezione descrive le best practice per aiutarti a ottenere il massimo dal servizio Place Autocomplete.
Di seguito sono riportate alcune linee guida generali:
Comprendi fin da subito i campi di dati di completamento automatico dei luoghi.
I campi della geolocalizzazione e della 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 presenti una riduzione controllata se l'API restituisce un errore.
Assicurati che la tua app sia gestita quando non è presente alcuna selezione e offre agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare i costi di utilizzo del servizio di completamento automatico dei luoghi, utilizza le maschere di campo nei widget Dettagli luogo e Inserisci completamento automatico per restituire solo i campi di dati dei luoghi necessari.
Ottimizzazione avanzata dei costi
Prendi in considerazione l'implementazione programmatica del completamento automatico di Place per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding anziché il luogo selezionato, anziché Dettagli luogo. I prezzi per richiesta abbinati all'API Geocoding sono più vantaggiosi dei prezzi per sessione (basati su sessione) se sono soddisfatte entrambe le seguenti condizioni:
Se ti servono soltanto la latitudine/longitudine o l'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni per meno di una chiamata con Dettagli luogo.
Se gli utenti selezionano una previsione di completamento automatico entro una media di massimo quattro richieste di previsioni di completamento automatico, il prezzo per richiesta potrebbe essere più conveniente di quello per sessione.
Per aiutarti a selezionare l'implementazione di Place Autocomplete adatta alle tue esigenze, seleziona la scheda che corrisponde 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 completamento automatico dei luoghi:
Aggiungi limitazioni in base al paese, la previsione della località e (per le implementazioni programmatiche) la preferenza della lingua per l'implementazione del completamento automatico del luogo. La preferenza della lingua non è necessaria
per i widget perché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
Se il completamento automatico di un luogo è accompagnato da una mappa, puoi modificare la posizione in base alla visualizzazione della mappa.
Nei casi in cui un utente non scelga una delle previsioni di completamento automatico, 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 debba inserire solo le informazioni relative all'indirizzo, riutilizza l'input utente originale durante una chiamata all'API Geocoding.
Se prevedi che l'utente inserirà query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Trova luogo.
Se i risultati sono previsti solo in una regione specifica, utilizza la previsione della località.
Altri scenari in cui è meglio utilizzare l'API Geocoding sono i seguenti:
Gli utenti che inseriscono indirizzi di premessa nei paesi in cui il supporto della funzionalità di completamento automatico degli indirizzi di pre-ordine sono incompleti, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" genera una previsione parziale nel Place Autocomplete.
Gli utenti che inseriscono indirizzi con prefissi del segmento di strada come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.
