Introduzione
Il completamento automatico è una funzionalità della libreria Places dell'API Maps JavaScript. Puoi utilizzare il completamento automatico per assegnare alle tue applicazioni il comportamento di ricerca type-ahead del campo di ricerca di Google Maps. Il servizio di completamento automatico può creare corrispondenze con parole complete e sottostringhe, risolvendo nomi di luoghi, indirizzi e più codici. Le applicazioni possono quindi inviare query come tipo di utente per fornire previsioni immediate sui luoghi. Come definito dall'API Places, un "luogo" può essere un'attività, una posizione geografica o un punto d'interesse evidente.
Per 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.
Per visualizzare l'elenco delle API abilitate:
- Vai alla console Google Cloud.
- Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
- Nell'elenco delle API nella dashboard, cerca API Places.
- Se vedi l'API nell'elenco, non devi eseguire altre operazioni. Se l'API non è nell'elenco,
abilitala:
- Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
- Cerca l'API Places, quindi selezionala dall'elenco dei risultati.
- Seleziona ABILITA. Al termine della procedura, l'API Places viene visualizzata nell'elenco delle API nella dashboard.
Caricamento della libreria 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 di Google Maps:
<script async
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&loading=async&libraries=places&callback=initMap">
</script>
Per ulteriori informazioni, consulta la panoramica delle librerie.
Riepilogo dei corsi
L'API offre due tipi di widget con 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 Maps JavaScript:
classe AutocompleteService).
Di seguito è riportato un riepilogo dei corsi disponibili:
-
Autocomplete
aggiunge un campo di immissione di testo alla pagina web e monitora questo campo per rilevare i caratteri. Mentre l'utente inserisce il testo, il completamento automatico restituisce le previsioni 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 dall'applicazione. Consulta i dettagli di seguito. -
SearchBox
aggiunge un campo di immissione di testo alla pagina web, in modo molto analogo aAutocomplete
. Le differenze sono le seguenti:- La differenza principale risiede nei risultati che appaiono 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", la lista di selezione potrebbe includere la frase "pizza a Roma a Milano" e i nomi di varie pizzerie. SearchBox
offre meno opzioni rispetto aAutocomplete
per limitare la ricerca. Nel primo, puoi differenziare la ricerca in base a un determinatoLatLngBounds
. Nel secondo caso, puoi limitare la ricerca a un paese e a tipi di luogo specifici, nonché impostare i limiti. Per maggiori informazioni, vedi di seguito.
- La differenza principale risiede nei risultati che appaiono nell'elenco di selezione.
- Puoi creare un oggetto
AutocompleteService
per recuperare le previsioni in modo programmatico. ChiamagetPlacePredictions()
per recuperare i luoghi corrispondenti oppure chiama il numerogetQueryPredictions()
per recuperare i luoghi corrispondenti insieme ai termini di ricerca suggeriti. Nota:AutocompleteService
non aggiunge alcun controllo dell'interfaccia utente. I metodi sopra riportati, invece, restituiscono 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 Autocomplete
Il widget Autocomplete
crea un campo di immissione di testo nella pagina web, fornisce previsioni dei luoghi in un elenco di scelta dell'interfaccia utente e restituisce i dettagli sui luoghi in risposta a una richiesta getPlace()
. Ogni voce nell'elenco di selezione corrisponde a una singola posizione (come definita dall'API Places).
Il costruttore Autocomplete
accetta due argomenti:
- Un elemento HTML
input
di tipotext
. 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 rispostaPlace Details
per il parametroPlaceResult
selezionato dall'utente. Se la proprietà non è impostata o se viene trasmesso['ALL']
, vengono restituiti e fatturati tutti i campi disponibili (questa operazione non è consigliata per i deployment di produzione). Per un elenco dei campi, vediPlaceResult
. - Un array di
types
che specifica un tipo esplicito o una raccolta di tipi, come elencato tra i tipi supportati. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi. bounds
è un oggettogoogle.maps.LatLngBounds
che specifica l'area in cui cercare luoghi. I risultati sono sbilanciati, ma non limitati, ai luoghi contenuti in questi limiti.strictBounds
è unboolean
che specifica se l'API deve restituire solo i luoghi che si trovano rigorosamente all'interno della regione definita dalbounds
specificato. L'API non restituisce risultati al di fuori di questa regione anche se corrispondono all'input dell'utente.- Puoi utilizzare
componentRestrictions
per limitare i risultati a gruppi specifici. Al momento, puoi utilizzarecomponentRestrictions
per filtrare in base a un massimo di cinque paesi. I paesi devono essere trasmessi come codice paese a 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 sul codice nella pagina Wikipedia: List of ISO 3166 country code (Elenco dei codici paese ISO 3166) o sulla ISO Online Browsing Platform.
placeIdOnly
può essere utilizzato per indicare al widgetAutocomplete
di recuperare solo gli ID luogo. Quando chiamigetPlace()
sull'oggettoAutocomplete
, perPlaceResult
reso disponibile saranno impostate solo le proprietàplace id
,types
ename
. Puoi utilizzare l'ID luogo restituito con chiamate ai servizi Places, Geocoding, Directions o Distance Matrix.
- Un array di dati
Vincolo delle previsioni di Completamento automatico
Per impostazione predefinita, la funzionalità di completamento automatico di luoghi presenta tutti i tipi di luogo, con influenza sulle previsioni relative alla località in cui si trova l'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 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 i luoghi di tipo establishment
, dando la priorità a quelli all'interno dell'area geografica specificata e limitando le previsioni solo ai luoghi degli Stati Uniti. La configurazione 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);
JavaScript
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"); 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
Specifica i campi di dati per evitare che ti vengano addebitati SKU di dati Places non necessari. Includi la proprietà fields
nel AutocompleteOptions
che vengono passati al costruttore del widget, come mostrato nell'esempio precedente, o chiama setFields()
su un oggetto Autocomplete
esistente.
autocomplete.setFields(["place_id", "geometry", "name"]);
Definisci i bias e i confini dell'area di ricerca per il completamento automatico
Puoi differenziare i risultati del completamento automatico in modo da favorire una posizione o un'area approssimativa, nei seguenti modi:
- Imposta i limiti alla creazione dell'oggetto
Autocomplete
. - Modifica i limiti su un elemento
Autocomplete
esistente. - Imposta i limiti sull'area visibile della mappa.
- Limita la ricerca ai limiti.
- Limitare la ricerca a un paese specifico.
L'esempio precedente mostra i limiti di impostazione al momento della creazione. I seguenti esempi dimostrano le altre tecniche di differenziazione.
Modificare i limiti di un completamento automatico esistente
Richiama setBounds()
per modificare l'area di ricerca di un
Autocomplete
esistente in limiti rettangolari.
TypeScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
JavaScript
const southwest = { lat: 5.6108, lng: 136.589326 }; const northeast = { lat: 61.179287, lng: 2.64325 }; const newBounds = new google.maps.LatLngBounds(southwest, northeast); autocomplete.setBounds(newBounds);
Imposta i limiti sull'area visibile della mappa
Utilizza bindTo()
per differenziare i risultati nell'area visibile della mappa, anche se quest'ultima cambia.
TypeScript
autocomplete.bindTo("bounds", map);
JavaScript
autocomplete.bindTo("bounds", map);
Utilizza unbind()
per svincolare le previsioni di Completamento automatico dall'area visibile della mappa.
TypeScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
JavaScript
autocomplete.unbind("bounds"); autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
Limita la ricerca ai limiti attuali
Imposta l'opzione strictBounds
per limitare i risultati ai limiti correnti, in base all'area visibile della mappa o ai limiti rettangolari.
autocomplete.setOptions({ strictBounds: true });
Limitare le previsioni a un paese specifico
Utilizza l'opzione componentRestrictions
o chiama setComponentRestrictions()
per limitare la
ricerca con completamento automatico a un gruppo specifico di massimo cinque paesi.
TypeScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
JavaScript
autocomplete.setComponentRestrictions({ country: ["us", "pr", "vi", "gu", "mp"], });
Vincola tipi di luoghi
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:
Un array contenente fino a cinque valori della Tabella 1 o della Tabella 2 dei Tipi di luogo. Ad esempio:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Oppure:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Qualsiasi filtro nella Tabella 3 di Tipi di luogo. Puoi specificare un solo valore dalla Tabella 3.
La richiesta verrà rifiutata se:
- Puoi specificare più di cinque tipi.
- Specifica eventuali tipi non riconosciuti.
- Puoi combinare qualsiasi tipo di filtro della Tabella 1 o della Tabella 2 con qualsiasi filtro della Tabella 3.
La demo di Places Autocomplete mostra le differenze nelle previsioni tra i diversi tipi di luoghi.
Recupero delle informazioni sul luogo in corso...
Quando un utente seleziona un luogo dalle previsioni allegate al campo di testo del completamento automatico, il servizio attiva un evento place_changed
. Per ottenere i dettagli sul luogo:
- Crea un gestore di eventi per l'evento
place_changed
e chiamaaddListener()
sull'oggettoAutocomplete
per aggiungere il gestore. - Chiama
Autocomplete.getPlace()
sull'oggettoAutocomplete
per recuperare un oggettoPlaceResult
, che puoi utilizzare per ottenere maggiori informazioni sul luogo selezionato.
Per impostazione predefinita, quando un utente seleziona un luogo, il completamento automatico restituisce tutti i
campi di dati disponibili per il luogo selezionato e ti verranno fatturati di conseguenza.
Utilizza Autocomplete.setFields()
per specificare quali campi dei dati dei luoghi 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 utilizzare Autocomplete.setFields()
per specificare solo i dati dei luoghi che utilizzerai.
La proprietà name
contiene le previsioni
description
del completamento automatico di Places. Puoi scoprire di più su description
nella documentazione di Places Autocomplete.
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(); }
JavaScript
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;
Personalizzazione del testo segnaposto
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 nell'applicazione. Per informazioni su come l'API Google Maps JavaScript sceglie la lingua da utilizzare, leggi la documentazione sulla localizzazione.
Per personalizzare l'aspetto del widget, consulta la sezione Stili dei widget Completamento automatico e SearchBox.
Aggiunta di un widget SearchBox
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 Roma".
Puoi allegare SearchBox
a un campo di testo e, man mano che inserisci 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) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuova", la lista di selezione potrebbe includere la frase "pizza a Roma a Milano" e i nomi di diverse 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 tipotext
. Questo è il campo di immissione che il servizioSearchBox
monitorerà e a cui collegherà i risultati. - Un argomento
options
, che può contenere la proprietàbounds
:bounds
è un oggettogoogle.maps.LatLngBounds
che specifica l'area in cui cercare luoghi. I risultati sono differenziati, a titolo esemplificativo, per i luoghi contenuti all'interno di questi limiti.
Il seguente codice utilizza il parametro dei limiti per polarizzare i risultati in base ai luoghi all'interno di una determinata area geografica, specificati tramite coordinate di laitudine/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 per SearchBox
Per modificare l'area di ricerca per un elemento SearchBox
esistente, chiama
setBounds()
sull'oggetto SearchBox
e trasmetti
l'oggetto LatLngBounds
pertinente.
Recupero delle informazioni sul luogo in corso...
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 saperne di più sull'oggetto PlaceResult
, consulta la documentazione sui
risultati dei dettagli dei luoghi.
TypeScript
// 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); });
JavaScript
// 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); });
Per personalizzare l'aspetto del widget, consulta la sezione Stili dei widget Completamento automatico e SearchBox.
Recupero programmatico del servizio Place Autocomplete
Per recuperare le previsioni in modo programmatico, utilizza la
classe AutocompleteService
. AutocompleteService
non aggiunge alcun controllo dell'interfaccia utente. Restituisce invece un array di oggetti di previsione, ciascuno contenente il testo della previsione, le informazioni di riferimento e i dettagli di come il risultato corrisponde all'input dell'utente.
Ciò è utile se vuoi un maggiore controllo sull'interfaccia utente rispetto a quello offerto da Autocomplete
e SearchBox
descritto sopra.
AutocompleteService
espone i seguenti metodi:
getPlacePredictions()
restituisce le previsioni sui luoghi. Nota: un "luogo" può essere un'attività, 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", la lista di selezione potrebbe includere la frase "pizza a Roma a Milano" e i nomi di varie pizzerie.
Entrambi i metodi precedenti restituiscono un array di oggetti di previsione nel formato seguente:
description
è la previsione corrispondente.distance_meters
è la distanza in metri del luogo dalAutocompletionRequest.origin
specificato.matched_substrings
contiene un insieme di sottostringhe nella descrizione che corrispondono agli elementi 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 di caratteri, misurato dall'inizio della stringa descrittiva, in cui viene visualizzata la sottostringa corrispondente.
place_id
è un identificatore testuale che identifica in modo univoco un luogo. Per recuperare informazioni sul luogo, passa questo identificatore nel campoplaceId
di una richiesta Dettagli luogo. Scopri di più su come fare riferimento a un luogo con un ID luogo.terms
è un array che contiene gli 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 viene visualizzata la sottostringa corrispondente.value
è il termine corrispondente.
L'esempio seguente esegue una richiesta di previsione della query per la frase "pizza nelle vicinanze" e mostra il risultato in un elenco.
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> 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;
JavaScript
// 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;
CSS
HTML
<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>
Prova Sample
Token di sessione
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 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 si conclude quando seleziona un luogo. Ogni sessione può includere più query, seguite da una selezione di un luogo.
Al termine di una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Consigliamo di usare 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 un token di sessione (ogni richiesta viene fatturata separatamente).
Puoi utilizzare lo stesso token di sessione per effettuare una singola richiesta
Place Details
(Dettagli luogo) sul 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ù sessioni Autocomplete renderà non valide quelle sessioni Autocomplete, mentre tutte le richieste di Autocomplete nelle sessioni non valide verranno addebitate singolarmente utilizzando lo SKU Autocomplete Per richiesta SKU. Scopri di più sui token di sessione.
L'esempio seguente mostra la creazione di un token di sessione e poi il 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 passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più sessioni comporterà la fatturazione individuale di ogni richiesta.
Scopri di più sui token di sessione.
Stili dei widget Autocomplete e SearchBox
Per impostazione predefinita, agli elementi dell'interfaccia utente forniti da Autocomplete
e SearchBox
viene applicato uno stile per l'inclusione su una mappa di Google. Ti consigliamo di
modificare lo stile per adattarlo al tuo sito. Sono disponibili le seguenti classi CSS. Tutti i corsi elencati di seguito si applicano sia ai
widget Autocomplete
che a quelli SearchBox
.
Classe CSS | Descrizione |
---|---|
pac-container |
L'elemento visivo contenente l'elenco delle previsioni restituite dal servizio Place Autocomplete. Questo elenco viene visualizzato come elenco a discesa sotto il widget Autocomplete o SearchBox . |
pac-icon |
L'icona visualizzata a sinistra di ogni elemento nell'elenco 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 sopra il puntatore del mouse. |
pac-item-selected |
L'elemento quando l'utente lo seleziona tramite la tastiera. Nota: gli elementi selezionati faranno parte di questo corso e di pac-item .
|
pac-item-query |
Un intervallo all'interno di pac-item che è la parte principale della previsione. Per le località geografiche, contiene il nome di un luogo, come "Sydney", o il nome di una via e un numero civico, ad esempio "Via Roma 10". Per
ricerche basate su testo, ad esempio "pizza a New York", questo parametro contiene il testo completo
della query. Per impostazione predefinita, il campo pac-item-query è di colore nero. Se è presente testo aggiuntivo in pac-item , si trova all'esterno di pac-item-query e ne 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 viene evidenziato in grassetto. Tieni presente che il
testo corrispondente può trovarsi ovunque all'interno di pac-item . Non fa necessariamente parte di pac-item-query e potrebbe essere in parte all'interno di pac-item-query e in parte nel testo rimanente in pac-item . |
Utilizzo del componente Selettore di luogo
Nota:questo esempio utilizza una libreria open source. Consulta la pagina README per ricevere assistenza e feedback relativi alla libreria.
Prova i componenti web. Utilizza il componente web Selettore di luoghi per abilitare l'inserimento di testo che consenta agli utenti finali di cercare un indirizzo o un luogo specifico utilizzando il completamento automatico.
Posiziona ottimizzazione del completamento automatico
In questa sezione vengono descritte le best practice per aiutarti a ottenere il massimo dal servizio Place Autocomplete.
Ecco alcune linee guida generali:
- Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget Autocomplete dell'API Maps JavaScript, il widget Autocomplete dell'SDK Places per Android o il controllo dell'interfaccia utente di Autocomplete dell'SDK Places per iOS
- Sviluppa sin dall'inizio una comprensione dei campi di dati essenziali di Place Autocomplete.
- I campi per la differenziazione per località e per le limitazioni in base alla 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 sia in grado di gestire quando non è possibile effettuare selezioni e di offrire agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere dei campi nei widget Place Details e Place Autocomplete per restituire solo i campi dei dati del luogo necessari.
Ottimizzazione avanzata dei costi
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 ti servono solo la latitudine/longitudine o l'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, il prezzo Per richiesta potrebbe essere più conveniente rispetto al prezzo Per sessione.
La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?
Sì, sono necessari altri dettagli
Utilizza il completamento automatico basato sulla sessione con Place Details.
Poiché la tua applicazione richiede Place Details come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Place Autocomplete deve utilizzare un token di sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per un costo totale di 0,017 $per sessione oltre agli SKU di dati di Places applicabili in base ai campi dei dati dei luoghi richiesti.
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete che la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields
per assicurarti di richiedere solo i campi dei dati del luogo necessari.
Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi Place Details (Dettagli locale) per la previsione selezionata, includi i seguenti parametri:
- L'ID luogo nella risposta Place Autocomplete
- Il token di sessione utilizzato nella richiesta Place Autocomplete
- Il parametro
fields
che specifica i campi di dati del luogo necessari
No, richiede solo indirizzo e posizione
L'API Geocoding potrebbe essere un'opzione più economica rispetto a Place Details per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete. L'efficienza di completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, dove viene utilizzata l'applicazione e che sono state implementate best practice per l'ottimizzazione delle prestazioni.
Per rispondere alla seguente domanda, analizza il numero di caratteri digitati in media da un utente prima di selezionare una previsione di Place Autocomplete nella tua applicazione.
I tuoi utenti selezionano una previsione di Place Autocomplete in una media di quattro o meno richieste?
Sì
Implementa Place Autocomplete in modo programmatico senza token di sessione e chiama l'API Geocoding nella previsione del luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine al costo di 0,005 $per richiesta. Effettuare quattro richieste Place Autocomplete - Per Request costa $0,01132; il costo totale di quattro richieste più una chiamata API Geocoding per la previsione del luogo selezionata sarebbe di $0,01632, che è inferiore al prezzo del completamento automatico per sessione di $0,017 per sessione.1
Valuta la possibilità di adottare le best practice per il rendimento per consentire agli utenti di ottenere le previsioni che cercano utilizzando ancora meno caratteri.
No
Utilizza il completamento automatico basato sulla sessione con Place Details.
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di Place Autocomplete supera il costo dei prezzi per sessione, l'implementazione di Place Autocomplete deve utilizzare un token di sessione sia per le richieste Place Autocomplete sia per la richiesta Place Details associata per un costo totale di 0,017 $per sessione.1
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete che la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields
per avere la certezza di richiedere solo i campi Dati di base.
Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi Place Details (Dettagli locale) per la previsione selezionata, includi i seguenti parametri:
- L'ID luogo nella risposta Place Autocomplete
- Il token di sessione utilizzato nella richiesta Place Autocomplete
- Il parametro
fields
che specifica i campi Dati di base come l'indirizzo e la geometria
Valuta l'idea di posticipare le richieste di Place Autocomplete
Puoi adottare strategie come il ritardo di una richiesta di Place Autocomplete finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, fare richieste Place Autocomplete per ogni carattere dopo che l'utente ha digitato il terzo carattere significa che se l'utente digita sette caratteri seleziona quindi una previsione per la quale effettui una richiesta all'API Geocoding, il costo totale sarà di $0,01632 (4 * $0,00283 Autocomplete Per Request + $0,005 Geocoding).1
Se con il ritardo le richieste di pubblicità programmatica sono inferiori alle quattro, puoi seguire le indicazioni per l'implementazione performante Place Autocomplete with Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di ottenere previsioni a ogni nuova pressione di un tasto.
Valuta la possibilità di applicare le best practice per il rendimento per consentire agli utenti di ottenere le previsioni che cercano con meno caratteri.
-
I costi elencati qui sono 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 come ottimizzare le prestazioni del completamento automatico di Place Auto:
- Aggiungi limitazioni in base al paese, differenziazione per località e (per le implementazioni di pubblicità programmatica) la preferenza della lingua all'implementazione di Place Autocomplete. La preferenza della lingua non è necessaria con i widget perché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
- Se il completamento automatico di Place Autocomplete è accompagnato da una mappa, puoi differenziare la posizione in base all'area visibile della mappa.
- Nei casi in cui un utente non sceglie una delle previsioni di Completamento automatico, in genere perché nessuna di queste previsioni rappresenta l'indirizzo dei risultati 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à.
- 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" restituisce una previsione parziale in Place Autocomplete.
- Gli utenti che inseriscono indirizzi con prefissi dei segmenti di strada come "23-30 29th St, Queens" a New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.
Limiti e norme di utilizzo
Quote
Per informazioni su quote e prezzi, consulta la documentazione relativa all'utilizzo e alla fatturazione per l'API Places.
Criteri
L'utilizzo della libreria Places, l'API Maps JavaScript deve essere conforme alle norme descritte per l'API Places.