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 Google Maps Services. La pagina
all'indirizzo
questo link introduce anche i client Java,
Python e 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 da digitare del campo di ricerca di Google Maps.
Il servizio di completamento automatico può creare corrispondenze con parole complete e sottostringhe, risolvendo
nomi dei luoghi, indirizzi e plus
codici. Le applicazioni possono quindi inviare query durante i tipi di utenti per
fornire previsioni immediate sui luoghi.
Come iniziare
Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia attivata nella console Google Cloud nello stesso progetto che hai configurato per l'API Maps JavaScript.
Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
Nell'elenco delle API sulla dashboard, cerca
l'API Places.
Se l'API è presente nell'elenco, significa che è tutto a posto. Se l'API non è nell'elenco,
abilitala:
Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Libreria dal menu a sinistra.
Cerca l'API Places, quindi selezionala dall'elenco dei risultati.
Seleziona ABILITA. Al termine del processo,
l'API Places viene visualizzata nell'elenco delle API sulla
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 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 del completamento automatico in modo programmatico (consulta la pagina di riferimento dell'API JavaScript di Maps:
classe AutocompleteService).
Di seguito è riportato un riepilogo dei corsi disponibili:
Autocomplete aggiunge un campo di immissione di testo alla pagina web
e monitora tale campo per rilevare eventuali voci di caratteri. Mentre 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 relative informazioni vengono restituite all'oggetto con completamento automatico e possono essere recuperate dall'applicazione. Vedi i dettagli di seguito.
Figura 1: elenco di selezione e campo di testo con completamento automaticoFigura 2: modulo di 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 può includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza nuova", l'elenco di selezione può includere la frase "pizza a New York, NY" e i nomi di varie pizzerie.
SearchBox offre meno opzioni rispetto a
Autocomplete per limitare la ricerca. Nel primo caso, puoi differenziare la ricerca in base a un determinato LatLngBounds. Nel secondo caso, puoi limitare la ricerca a un determinato paese e a determinati tipi di luogo, nonché impostare dei limiti. Per ulteriori informazioni, vedi
di seguito.
Figura 3: una casella di ricerca presenta i termini di ricerca e le previsioni sui 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 chiama getQueryPredictions() per
recuperare i luoghi corrispondenti e i termini di ricerca suggeriti.
Nota: AutocompleteService non aggiunge alcun controllo dell'interfaccia utente.
I metodi sopra riportati restituiscono invece un array di oggetti di previsione. Ogni oggetto di previsione contiene il testo della previsione, nonché informazioni di riferimento e dettagli di come il risultato corrisponde all'input utente. Consulta i
dettagli di seguito.
Aggiunta di un widget Completamento automatico
Il widget Autocomplete crea un campo di immissione di testo nella 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 collegherà 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 parametro PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene passato ['ALL'], tutti i campi disponibili vengono restituiti e fatturati per (questa operazione non è consigliata per i deployment di produzione). Per un elenco dei campi, vedi PlaceResult.
Un array di types che specifica un tipo esplicito o una raccolta di tipi, come elencato nei tipi supportati. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi.
bounds è un oggetto google.maps.LatLngBounds che specifica
l'area in cui cercare i luoghi. I risultati sono influenzati, 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 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 codici paese a due caratteri compatibili con lo standard ISO 3166-1 Alpha-2. È necessario trasmettere più paesi 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 di interesse geografico speciali che intendi. Puoi trovare informazioni sul codice 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. Alla chiamata di
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 Luoghi, Geocodifica, Indicazioni stradali o Matrice di distanze.
Vincolo di previsioni di completamento automatico
Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luoghi, differenziati per le previsioni relative alla località 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 caso d'uso.
Imposta opzioni in fase di allestimento
Il costruttore Autocomplete accetta un parametro AutocompleteOptions
per impostare vincoli al momento della creazione del widget. L'esempio seguente imposta le opzioni
bounds, componentRestrictions e types per
richiedere i luoghi di tipo establishment, favorendo quelli all'interno dell'area geografica
specificata e limitando le previsioni solo ai luoghi negli Stati Uniti. L'impostazione dell'opzione
fields consente di specificare le informazioni da restituire sul luogo selezionato dall'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 di dati per evitare addebiti per gli SKU di dati di Places non necessari. Includi nella AutocompleteOptions la proprietà fields che vengono passate al costruttore del widget, come mostrato nell'esempio precedente, oppure chiama setFields() su un oggetto Autocomplete esistente.
Imposta l'opzione strictBounds per limitare i risultati ai limiti attuali, in base alla visualizzazione 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 completamento automatico a un gruppo 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 luogo.
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
di completamento automatico, il servizio attiva un evento place_changed. Per ottenere i dettagli del 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 verranno fatturati addebiti.
Utilizza Autocomplete.setFields()
per specificare i campi 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 non necessari, assicurati di usare Autocomplete.setFields() per specificare solo i dati del luogo che utilizzerai.
Per i moduli dell'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
dell'indirizzo.
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 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 quel valore nella tua applicazione. Per informazioni su come l'API JavaScript di Google Maps sceglie il linguaggio da utilizzare, leggi la documentazione sulla
localizzazione.
Il SearchBox consente agli utenti di eseguire una ricerca geografica
basata su testo, ad esempio "pizza a New York" o "negozi di scarpe vicino a Roma".
Puoi allegare SearchBox a un campo di testo e, man mano che viene inserito il testo, il servizio restituirà previsioni sotto forma di elenco a discesa.
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 nuova", l'elenco di selezione può includere la frase "pizza a New York, NY" e i nomi di varie pizzerie. Quando un utente seleziona un luogo dall'elenco,
le relative informazioni 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 il servizio SearchBox monitorerà e 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 luoghi. I risultati sono influenzati, ma non limitati, ai luoghi contenuti all'interno di questi limiti.
Il codice seguente utilizza il parametro dei limiti per differenziare i risultati in base ai luoghi all'interno di una determinata area geografica, specificati tramite 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
});
Modifica dell'area di ricerca della casella di ricerca
Per modificare l'area di ricerca per un SearchBox esistente, chiama
setBounds() sull'oggetto SearchBox e trasmetti
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() sull'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 del servizio di completamento automatico di Place a livello di programmazione
Per recuperare le previsioni in modo programmatico, utilizza la
AutocompleteService. AutocompleteService non aggiunge alcun controllo UI. Restituisce invece un array di oggetti di previsione, ciascuno contenente il testo della previsione, informazioni di riferimento e dettagli di come il risultato corrisponde all'input utente.
Questa soluzione è utile se vuoi avere un maggiore controllo sull'interfaccia utente rispetto a quanto offerto dai Autocomplete e SearchBox descritti sopra.
AutocompleteService espone i seguenti metodi:
getPlacePredictions() restituisce le previsioni dei luoghi.
Nota: un "luogo" può essere un luogo, una posizione geografica o un punto d'interesse di rilievo, 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 nuova", l'elenco di selezione può includere la frase "pizza a Roma, Italia" 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 dal
AutocompletionRequest.origin specificato.
Nella descrizione matched_substrings contiene un insieme di sottostringhe che corrispondono agli elementi nell'input dell'utente. Ciò è utile per evidenziare queste sottostringhe nell'applicazione. In molti casi, la query verrà visualizzata come sottostringa del campo Descrizione.
length è la lunghezza della sottostringa.
offset è l'offset di caratteri, misurato dall'inizio della stringa descrittiva, in cui appare la sottostringa corrispondente.
place_id è un identificatore testuale che identifica in modo univoco un luogo. Per recuperare informazioni sul luogo, passa questo identificatore
nel campo placeId di una
richiesta
Place Details. Scopri di più su come
fare riferimento a un luogo
con l'ID luogo.
terms è un array contenente elementi della query. Per
un luogo, in genere ogni elemento costituisce una parte dell'indirizzo.
offset è l'offset di caratteri, misurato dall'inizio della stringa descrittiva, in cui appare 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">
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 ai fini della fatturazione. I token di sessione raggruppano le fasi di query e selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina quando seleziona un luogo. Ogni sessione può includere 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. 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).
Puoi utilizzare lo stesso token di sessione per effettuare una singola richiesta
Place Details
per il luogo generato da una chiamata a AutocompleteService.getPlacePredictions().
In questo caso, la richiesta di completamento automatico viene combinata con la richiesta Place Details e la chiamata viene addebitata come una normale richiesta Place Details. Non è previsto alcun costo per la
richiesta di completamento automatico.
Assicurati di trasmettere un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più sessioni di completamento automatico renderà non valide le sessioni di completamento automatico e tutte le richieste di completamento automatico nelle sessioni non valide verranno addebitate singolarmente 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 successivo passaggio 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 trasmettere un token di sessione univoco per ogni nuova sessione. Se utilizzi lo stesso token per più sessioni, ogni richiesta verrà fatturata individualmente.
Stili dei widget Completamento automatico e SearchBox
Per impostazione predefinita, gli elementi dell'interfaccia utente forniti da Autocomplete e SearchBox vengono definiti per l'inclusione in una mappa Google. Ti consigliamo di
adattare lo stile al tuo sito. Sono disponibili le seguenti classi CSS. Tutte le classi elencate di seguito si applicano sia ai widget Autocomplete che a SearchBox.
Classi CSS per i widget Autocomplete e SearchBox
Classe CSS
Descrizione
pac-container
L'elemento visivo contenente l'elenco delle previsioni restituite dal servizio Place Autocomplete. L'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
Una voce nell'elenco di previsioni fornito dal widget Autocomplete o SearchBox.
pac-item:hover
L'elemento quando l'utente ci passa sopra il puntatore del mouse.
pac-item-selected
L'elemento quando l'utente lo seleziona tramite tastiera. Nota: gli elementi selezionati faranno parte di questa classe e di pac-item.
pac-item-query
Un intervallo all'interno di un pac-item che è la parte principale della
previsione. Per le località geografiche, contiene il nome di un luogo, ad esempio "Sydney", oppure il nome e il numero di una via, ad esempio "Via Roma 10". Per le ricerche basate su testo come "pizza a New York", contiene il testo completo della query. Per impostazione predefinita, il pac-item-query è di colore nero. Se è presente testo aggiuntivo in pac-item, è
esterno a pac-item-query e eredita il suo 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 può trovarsi ovunque 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.
Ottimizzazione del completamento automatico dei luoghi
Questa sezione descrive le best practice per aiutarti a utilizzare al meglio il servizio Place Autocomplete.
Di seguito sono riportate alcune linee guida generali:
Sviluppa una comprensione dei campi di dati essenziali di Place Autocomplete sin dall'inizio.
I campi relativi alla differenziazione per località e alla 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 venga ridotta correttamente se l'API restituisce un errore.
Assicurati che la tua app gestisca quando non c'è 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 di campo nei widget Place Details e Place Autocomplete per restituire solo i campi dei dati dei luoghi necessari.
Ottimizzazione dei costi avanzata
Prendi in considerazione 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 (basati su sessione) se vengono soddisfatte entrambe le seguenti condizioni:
Se hai bisogno solo della latitudine/longitudine o dell'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni per meno di una chiamata Place Details.
Se gli utenti selezionano una previsione di completamento automatico in una media di quattro richieste di previsioni 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 Place Autocomplete 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?
I costi elencati qui sono espressi in dollari statunitensi. Per informazioni complete sui prezzi, consulta la pagina Fatturazione di Google Maps Platform.
Best practice per il rendimento
Le seguenti linee guida descrivono i modi per ottimizzare le prestazioni del completamento automatico di Place:
Aggiungi restrizioni in base al paese,
differenziazione per località
e (per le implementazioni programmatiche) preferenze linguistiche all'implementazione di Place Autocomplete. La preferenza della lingua non è necessaria per i widget, perché questi ultimi scelgono la lingua dal browser o dal dispositivo mobile dell'utente.
Se Place Autocomplete è accompagnato da una mappa, puoi differenziare la posizione in base alla visualizzazione della mappa.
Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico, in genere perché nessuna di queste previsioni rappresenta l'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per cercare 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 per nome o indirizzo, utilizza una richiesta Trova luogo.
Se i risultati sono previsti solo in una regione specifica, utilizza la differenziazione per località.
Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
Utenti che inseriscono indirizzi secondari in paesi in cui il supporto di Place Autocomplete per gli indirizzi secondari è incompleto, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" fornisce una previsione parziale in Place Autocomplete.
Gli utenti inseriscono gli indirizzi con prefissi del tratto di strada, ad esempio "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.
