Introduzione
Il completamento automatico è una funzionalità della raccolta Places nell'API Maps JavaScript. Puoi utilizzare il completamento automatico per assegnare alle tue applicazioni il comportamento di ricerca di tipo avanzato del campo di ricerca di Google Maps. Il servizio di completamento automatico può trovare corrispondenze con parole e sottostringhe complete, risolvendo nomi di luoghi, indirizzi e più . Le applicazioni possono quindi inviare query man mano che l'utente digita per fornire previsioni sui luoghi in tempo reale. Come definito dall'API Places, un "luogo" può essere un esercizio, una località geografica o un punto d'interesse prominente.
Per iniziare
Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia abilitata nella console Google Cloud, nella stessa configurato per l'API Maps JavaScript.
Per visualizzare l'elenco delle API abilitate:
- Vai alla sezione Console Google Cloud.
- Fai clic sul pulsante Seleziona un progetto, quindi seleziona lo stesso progetto che hai configurato. per l'API Maps JavaScript e fai clic su Apri.
- Nell'elenco delle API sulla Dashboard, cerca API Places.
- Se vedi l'API nell'elenco, non devi eseguire altre operazioni. Se l'API non è elencata,
abilitala:
- Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, nel menu a sinistra, seleziona Raccolta.
- Cerca API Places e selezionala dall'elenco dei risultati.
- Seleziona ATTIVA. Al termine della procedura, API Places viene visualizzata nell'elenco delle API nella dashboard.
Caricamento della libreria in corso...
Il servizio Places è una libreria indipendente, separata dalla piattaforma
Codice dell'API Maps JavaScript. Per utilizzare le funzionalità contenute
all'interno di questa libreria, devi prima caricarla utilizzando il parametro libraries
nell'URL di bootstrap dell'API Maps:
<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 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 documentazione di riferimento dell'API Maps JavaScript:
classe AutocompleteService).
Di seguito è riportato un riepilogo dei corsi disponibili:
-
Autocomplete
aggiunge un campo di immissione di testo alla pagina web e monitora il campo per le inserzioni di caratteri. Man mano che l'utente inserisce il testo, Il completamento automatico restituisce previsioni sui luoghi sotto forma di elenco a discesa. Quando l'utente seleziona un luogo dall'elenco, le informazioni sul luogo vengono restituite all'oggetto di completamento automatico e possono essere recuperate dalla tua applicazione. Consulta i dettagli di seguito. -
SearchBox
aggiunge un campo di immissione di testo alla tua pagina web, allo stesso modo diAutocomplete
. Le differenze sono le seguenti:- La differenza principale sta nel fatto che
i 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 a new", l'elenco di scelta potrebbe includere la frase "pizza a New York, NY", nonché i nomi di vari punti vendita di pizza. SearchBox
offre meno opzioni rispetto aAutocomplete
per limitare la ricerca. Nel primo caso, può differenziare la ricerca verso un determinatoLatLngBounds
. Nel secondo caso, puoi limitare la ricerca a un determinato paese e a determinati tipi di luoghi, nonché impostare i limiti. Per ulteriori informazioni, consulta di seguito.
- La differenza principale sta nel fatto che
i risultati visualizzati nell'elenco di selezione.
- Puoi creare un oggetto
AutocompleteService
per recuperare le previsioni in modo programmatico. ChiamagetPlacePredictions()
per recupera luoghi corrispondenti o chiamagetQueryPredictions()
per recupera luoghi corrispondenti e termini di ricerca suggeriti. Nota:AutocompleteService
non aggiunge alcun controllo UI. I metodi precedenti restituiscono invece un array di oggetti di previsione. Ciascuna Prediction contiene il testo della previsione, oltre al riferimento informazioni e dettagli su come il risultato corrisponde all'input dell'utente. Vedi i dettagli di seguito.
Aggiunta di un widget di completamento automatico
La Autocomplete
Il widget crea un campo di immissione di testo nella pagina web, fornisce previsioni sui luoghi in una scelta dell'interfaccia utente
dall'elenco e restituisce i dettagli del luogo in risposta a una richiesta getPlace()
. Ogni voce nel
corrisponde a un singolo luogo (come definito dall'API Places).
Il costruttore Autocomplete
accetta due argomenti:
- Un elemento HTML
input
di tipotext
. Si tratta del campo di immissione che il servizio di completamento automatico monitora e a cui allega i risultati. - Un argomento
AutocompleteOptions
facoltativo, che può contenere le seguenti proprietà:- Un array di dati
fields
da includere la rispostaPlace Details
per il valorePlaceResult
selezionato dall'utente. Se non è impostata oppure, se viene passato['ALL']
, vengono restituiti tutti i campi disponibili addebitato per (sconsigliato 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 nei 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 i luoghi. I risultati sono orientati verso, ma non limitati a, i luoghi contenuti all'interno di questi limiti.strictBounds
è unboolean
che specifica se l'API deve restituire solo i luoghi che si trovano strettamente all'interno della regione definita dabounds
specificato. L'API non restituisce risultati al di fuori di questa regione anche se corrispondenti all'input dell'utente.componentRestrictions
può essere utilizzato per limitare i risultati a gruppi specifici. Al momento, puoi utilizzare la linguacomponentRestrictions
per filtrare in base a un massimo di 5 paesi. I paesi devono essere trasmessi come paesi a due caratteri compatibili con ISO 3166-1 Alpha-2 le API nel tuo codice. 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 di interesse geografico speciali che intendi. Puoi trovare informazioni sui codici su Wikipedia: Elenco dei codici paese ISO 3166 o sulla piattaforma di navigazione online ISO.
placeIdOnly
può essere utilizzato per indicare al widgetAutocomplete
di recuperare solo gli ID luogo. Chiamata in corsogetPlace()
sull'oggettoAutocomplete
,PlaceResult
reso disponibile avrà soloplace id
, Proprietàtypes
ename
impostate. Puoi utilizzare il valore restituito ID luogo con chiamate a Places, Geocoding, Directions o Distance Matrix i servizi di machine learning.
- Un array di dati
Previsioni di completamento automatico vincolanti
Per impostazione predefinita, la funzionalità di completamento automatico dei luoghi presenta tutti i tipi di luoghi, con un bias per le previsioni nelle vicinanze della posizione dell'utente, e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta le opzioni di completamento automatico dei luoghi per presentare previsioni più pertinenti in base al tuo caso d'uso.
Imposta opzioni in fase di costruzione
Il costruttore Autocomplete
accetta un valore AutocompleteOptions
per impostare i vincoli durante la creazione del widget. L'esempio seguente imposta le opzioni bounds
, componentRestrictions
e types
per richiedere luoghi di tipo establishment
, privilegiando quelli all'interno dell'area geografica specificata e limitando le previsioni solo ai luoghi all'interno degli Stati Uniti. L'impostazione dell'opzione fields
specifica le informazioni da restituire sul luogo selezionato dall'utente.
Chiama setOptions()
per modificare il valore di un'opzione per un widget esistente.
TypeScript
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 di Places non necessari. Includi la proprietà fields
in AutocompleteOptions
da passare al costruttore del widget, come mostrato nell'esempio precedente, oppure chiama setFields()
su un oggetto Autocomplete
esistente.
autocomplete.setFields(["place_id", "geometry", "name"]);
Definisci i bias e i confini dell'area di ricerca per Completamento automatico
Puoi differenziare i risultati del completamento automatico per favorire un valore approssimato località o area, nei seguenti modi:
- Imposta i limiti per la creazione dell'oggetto
Autocomplete
. - Modifica i limiti in un elemento
Autocomplete
esistente. - Imposta i limiti per l'area visibile della mappa.
- Limita la ricerca ai limiti.
- Limita la ricerca a un paese specifico.
L'esempio precedente mostra come impostare i limiti al momento della creazione. I seguenti esempi dimostrano le altre tecniche di differenziazione.
Modifica i limiti di un completamento automatico esistente
Chiama setBounds()
per modificare l'area di ricerca su un elemento esistente
Da Autocomplete
a 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 per l'area visibile della mappa
Usa bindTo()
per differenziare i risultati in base all'area visibile della mappa,
anche quando cambia l'area visibile.
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 });
Limita le previsioni a un paese specifico
Usa l'opzione componentRestrictions
o chiama il numero setComponentRestrictions()
per limitare la
la ricerca con completamento automatico in 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"], });
Limitare i tipi di luoghi
Utilizza l'opzione types
o chiama setTypes()
per limitare le predizioni a determinati tipi di luoghi. Questo vincolo specifica un tipo o una raccolta di tipi, come elencato in Tipi di luoghi.
Se non viene specificato alcun vincolo, vengono restituiti tutti i tipi.
Per il valore dell'opzione types
o il valore passato a setTypes()
,
puoi specificare:
Un array contenente fino a cinque valori della Tabella 1 o la Tabella 2 da Tipi di luogo. Ad esempio:
types: ['hospital', 'pharmacy', 'bakery', 'country']
Oppure:
autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
- Qualsiasi filtro nella Tabella 3 da Tipi di luogo. Puoi specificare un solo valore della Tabella 3.
La richiesta verrà rifiutata se:
- Puoi specificare più di cinque tipi.
- Specifica eventuali tipi non riconosciuti.
- Puoi combinare qualsiasi tipo della Tabella 1 o della Tabella 2 con qualsiasi filtro della Tabella 3.
La demo di Place Autocomplete mostra le differenze nelle previsioni tra i diversi tipi di luoghi.
Ottenere informazioni sui luoghi
Quando un utente seleziona un luogo dalle previsioni associate 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 richiamaaddListener()
sull'oggettoAutocomplete
per aggiungere il gestore. - Chiama il numero
Autocomplete.getPlace()
sull'oggettoAutocomplete
, per recuperare unPlaceResult
che puoi utilizzare per ottenere maggiori informazioni sull'oggetto selezionato posto.
Per impostazione predefinita, quando un utente seleziona un luogo, il completamento automatico restituisce tutti i campi di dati disponibili per il luogo selezionato e ti verrà fatturato di conseguenza.
Utilizza Autocomplete.setFields()
per specificare i campi di dati del luogo da restituire. Scopri di più sugli
Oggetto PlaceResult
, incluso un elenco di campi dati dei luoghi che
che puoi richiedere. Per evitare di pagare per i dati che non ti servono, assicurati di utilizzare Autocomplete.setFields()
per specificare solo i dati dei luoghi che utilizzerai.
La proprietà name
contiene
description
dalle previsioni di completamento automatico di Places. Puoi scoprire di più su description
nella documentazione di Place Autocomplete.
Per i moduli di indirizzo, è utile ricevere l'indirizzo in formato strutturato. Per
restituire l'indirizzo strutturato del luogo selezionato, chiama
Autocomplete.setFields()
e specifica il campo address_components
.
L'esempio seguente utilizza il completamento automatico per compilare i campi di un indirizzo in un modulo di testo.
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
segnaposto standard. Per modificare il testo, imposta il valore
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 specificare il proprio valore segnaposto, è necessario gestirne la localizzazione nella tua applicazione. Per informazioni su come l'API Google Maps JavaScript sceglie la lingua da utilizzare, leggi la documentazione sulla localizzazione.
Per personalizzare l'aspetto dei widget, consulta Personalizzare lo stile dei widget di completamento automatico e della casella di ricerca.
Aggiunta di un widget SearchBox
Lo
SearchBox
consente agli utenti di eseguire un'area geografica basata su testo
cerca, ad esempio, "pizza a New York" o "negozi di scarpe vicino a Robson Street".
Puoi associare SearchBox
a un campo di testo e, man mano che il testo viene inserito, il servizio restituirà le previsioni sotto forma di un elenco di opzioni a discesa.
SearchBox
fornisce un elenco esteso di previsioni,
può includere luoghi (come definiti dall'API Places) oltre alla ricerca suggerita
termini. Ad esempio, se l'utente inserisce "pizza a new", l'elenco di scelta può includere la frase "pizza a New York, NY", nonché i nomi di vari punti vendita di pizza. Quando un utente seleziona un luogo dall'elenco,
informazioni su quel luogo vengono restituite all'oggetto SearchBox e possono essere
recuperato dalla tua applicazione.
Il costruttore SearchBox
accetta due argomenti:
- Un elemento HTML
input
di tipotext
. Si tratta del campo di immissione che il servizioSearchBox
monitorerà e a cui agganciare i risultati. - Un argomento
options
, che può contenere Proprietàbounds
:bounds
è ungoogle.maps.LatLngBounds
che specifica l'area in cui cercare luoghi. I risultati sono orientati, ma non limitati, ai luoghi contenuti limiti.
Il seguente codice utilizza il parametro bounds per differenziare i risultati verso luoghi all'interno di una determinata area geografica, specificata coordinate di latitudine e 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 la casella di ricerca
Per modificare l'area di ricerca per un SearchBox
esistente, chiama
setBounds()
sull'oggetto SearchBox
e passa il token
oggetto LatLngBounds
pertinente.
Ottenere informazioni sui luoghi
Quando l'utente seleziona un elemento dalle previsioni associate alla casella di ricerca, il servizio attiva un evento places_changed
. Puoi
chiama getPlaces()
sull'oggetto SearchBox
per
recupera un array contenente diverse previsioni, ciascuna delle quali
PlaceResult
oggetto.
Per saperne di più sull'oggetto PlaceResult
, consulta la documentazione relativa ai 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 dei widget, consulta Personalizzare lo stile dei widget di completamento automatico e della casella di ricerca.
Recupero delle previsioni di Place Autocomplete Service in modo programmatico
Per recuperare le previsioni in modo programmatico, utilizza
AutocompleteService
. AutocompleteService
non aggiunge controlli dell'interfaccia utente. Restituisce invece un array di oggetti di previsione, ciascuno contenente il testo della previsione, le informazioni di riferimento e i dettagli su come il risultato corrisponde all'input dell'utente.
Questa opzione è utile se vuoi un maggiore controllo sull'interfaccia utente rispetto a quelloofferto da Autocomplete
e SearchBox
descritti sopra.
AutocompleteService
espone i seguenti metodi:
getPlacePredictions()
restituisce le previsioni sui luoghi. Nota: un "luogo" può essere un esercizio, una località geografica o un punto d'interesse in evidenza, come definito dall'API Places.getQueryPredictions()
restituisce un elenco esteso di previsioni che possono includere luoghi (come definito dall'API Places) più i termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza a new", l'elenco di scelta potrebbe includere la frase "pizza a New York, NY", nonché i nomi di vari punti vendita di pizza.
Entrambi i metodi sopra riportati restituiscono un array di previsione con la seguente forma:
description
è la previsione corrispondente.distance_meters
è la distanza in metri del luogo da il valoreAutocompletionRequest.origin
specificato.matched_substrings
contiene un insieme di sottostringhe in descrizione che corrisponde agli elementi nell'input dell'utente. Questo è utile per evidenziare queste sottostringhe nella tua applicazione. In molti casi, la query viene visualizzata come sottostringa del campo della descrizione.length
è la lunghezza della sottostringa.offset
è l'offset dei caratteri, misurato dal inizio della stringa di descrizione, in corrispondenza della quale la sottostringa corrispondente .
place_id
è un identificatore testuale che identifica in modo univoco un luogo. Per recuperare informazioni sul luogo, passa questo identificatore il campoplaceId
di un Dettagli luogo richiesta. Scopri di più su come indica un luogo con un ID luogo.terms
è un array contenente gli elementi della query. Per un luogo, in genere ogni elemento costituisce una parte dell'indirizzo.offset
è l'offset dei caratteri, misurato dall'inizio della stringa di descrizione, in cui viene visualizzata la sottostringa corrispondente.value
è il termine corrispondente.
L'esempio riportato di seguito esegue una richiesta di previsione della query per la frase "pizza vicino" e visualizza il risultato in un elenco.
TypeScript
// This example retrieves autocomplete predictions programmatically from the // autocomplete service, and displays them as an HTML list. // This example requires the Places library. Include the libraries=places // parameter when you first load the API. For example: // <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places"> 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 a fini di fatturazione. I token di sessione raggruppano le fasi di query e selezione di una ricerca di completamento automatico dell'utente in una sessione distinta a fini di fatturazione. La sessione
inizia quando l'utente inizia a digitare una query e conclude quando seleziona una
posto. Ogni sessione può avere più query, seguite dalla selezione di un luogo.
Al termine di una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Ti consigliamo di utilizzare i token di sessione
tutte le sessioni di completamento automatico. Se il parametro sessionToken
è
omesso o se riutilizzi un token di sessione, la sessione viene addebitata come se
è 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
sul luogo risultante da una chiamata a AutocompleteService.getPlacePredictions()
.
In questo caso, la richiesta di completamento automatico viene combinata con la richiesta di dettagli sul luogo e la chiamata viene addebitata come una normale richiesta di dettagli sul luogo. La richiesta di completamento automatico non comporta alcun costo.
Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione Autocomplete ne invaliderà le sessioni e tutte le richieste Autocomplete nelle sessioni non valide verranno addebitate singolarmente utilizzando lo SKU Autocomplete per richiesta. Scopri di più sui token di sessione.
L'esempio seguente mostra la creazione di un token sessione, quindi il suo passaggio in un
AutocompleteService
(la funzione displaySuggestions()
è stata omessa per brevità):
// Create a new session token. 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. Lo stesso per più di una sessione comporterà l'addebito di ogni richiesta singolarmente.
Scopri di più sui token di sessione.
Stili dei widget Autocomplete e SearchBox
Per impostazione predefinita, gli elementi dell'interfaccia utente forniti da Autocomplete
e
SearchBox
sono stilizzati per l'inclusione in una mappa di Google. Potresti volere
per adattare lo stile al tuo sito. Le seguenti classi CSS sono
disponibili. Tutte le classi elencate di seguito si applicano sia ai widget Autocomplete
sia ai widget SearchBox
.
Classe CSS | Descrizione |
---|---|
pac-container |
L'elemento visivo contenente l'elenco delle previsioni restituite dal
Servizio Place Autocomplete. L'elenco viene visualizzato sotto forma di elenco a discesa sotto
Widget Autocomplete o SearchBox . |
pac-icon |
L'icona visualizzata a sinistra di ogni elemento nell'elenco di per le previsioni. |
pac-item |
Un elemento nell'elenco delle previsioni fornite dal
Widget Autocomplete o SearchBox . |
pac-item:hover |
L'elemento quando l'utente passa il mouse sopra. |
pac-item-selected |
L'elemento quando l'utente lo seleziona tramite la tastiera. Nota: elementi selezionati
sarà un membro di questo corso e del corso pac-item .
|
pac-item-query |
Un intervallo all'interno di un pac-item che costituisce la parte principale della
previsione. Per le località geografiche, contiene il nome di un luogo, ad esempio "Sydney", o il nome e il numero di una via, ad esempio "10 King Street". Per le ricerche basate su testo come "pizza a New York", contiene il testo completo della query. Per impostazione predefinita, il carattere pac-item-query è di colore
nero. Se è presente testo aggiuntivo in pac-item ,
all'esterno di pac-item-query ed eredita lo stile da
pac-item . Per impostazione predefinita è di colore grigio. Il testo aggiuntivo
è generalmente un indirizzo. |
pac-matched |
La parte della previsione restituita che corrisponde all'input dell'utente. Per impostazione predefinita, questo testo corrispondente è evidenziato in grassetto. Tieni presente che
il testo con corrispondenza può trovarsi ovunque all'interno di pac-item . Non è
necessariamente parte di pac-item-query e potrebbe essere in parte
all'interno di pac-item-query nonché in parte nel testo rimanente
nel mese di pac-item . |
Ottimizzazione del completamento automatico dei luoghi
Questa sezione descrive le best practice per aiutarti a ottenere il massimo Servizio Place Autocomplete.
Ecco alcune linee guida generali:
- Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare Widget di completamento automatico dell'API Maps JavaScript, Widget di completamento automatico dell'SDK Places per Android, o Places SDK per iOS Controllo UI con completamento automatico
- Acquisisci fin dall'inizio una conoscenza dei campi di dati essenziali per il completamento automatico dei luoghi.
- I campi di bias di località e limitazione della località sono facoltativi, ma possono avere un impatto significativo sul rendimento del completamento automatico.
- Utilizza la gestione degli errori per assicurarti che la tua app si deteriori correttamente se l'API restituisce un errore.
- Assicurati che la tua app gestisca la situazione in cui non viene effettuata alcuna selezione e offra agli utenti un modo per continuare.
Best practice per l'ottimizzazione dei costi
Ottimizzazione dei costi di base
Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere dei campi nei widget Dettagli dei luoghi e Place Autocomplete per restituire solo i campi dati dei luoghi di cui hai bisogno.
Ottimizzazione avanzata dei costi
Prendi in considerazione l'implementazione programmatica di Place Autocomplete per accedere ai prezzi per richiesta e richiedere risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details. Il prezzo Per richiesta abbinato all'API Geocoding è più conveniente rispetto al prezzo Per sessione (basato 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 a un costo inferiore rispetto a una chiamata Place Details.
- Se gli utenti selezionano una previsione di completamento automatico entro 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 altre informazioni oltre all'indirizzo e alla latitudine/longitudine della previsione selezionata?
Sì, sono necessari ulteriori dettagli
Utilizza la funzionalità di completamento automatico dei luoghi basata sulla sessione con i dettagli dei luoghi.
Poiché la tua applicazione richiede Place Details come il nome del luogo, lo stato dell'attività o l'orario di apertura, per l'implementazione di Place Autocomplete è necessario 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 a SKU di dati di Places in base ai campi di dati dei luoghi richiesti.13}{/14
Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste di completamento automatico dei luoghi sia la richiesta di dettagli dei luoghi per la previsione selezionata. Assicurati di specificare il parametro fields
per assicurarti di richiedere solo i
campi dati dei luoghi di cui hai bisogno.
Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi i dettagli dei luoghi relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo della risposta di Place Autocomplete
- Il token di sessione utilizzato nella richiesta Place Autocomplete
- Il parametro
fields
che specifica campi di dati del luogo necessari
No, sono necessari solo indirizzo e posizione
L'API Geocoding potrebbe essere un'opzione più conveniente di Dettagli dei luoghi per la tua applicazione, a seconda del rendimento dell'utilizzo di Completamento automatico dei luoghi. L'efficienza del completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, dove viene utilizzata l'applicazione e se sono state implementate le best practice per l'ottimizzazione del rendimento.
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.
In media, i tuoi utenti selezionano una previsione del completamento automatico dei luoghi in quattro o meno richieste?
Sì
Implementa Place Autocomplete in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione del luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine a 0,005 $ per richiesta. L'invio di quattro richieste Place Autocomplete - Per richiesta costa 0,01132 $, pertanto il costo totale di quattro richieste più una chiamata all'API Geocoding relativa alla previsione del luogo selezionato è pari a 0,01632 $, inferiore al prezzo di 0,017 $ per sessione di Autocomplete per sessione.1
Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con un numero ancora inferiore di caratteri.
No
Utilizza Place Autocomplete basato sulla sessione con Place Details.
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione Place Autocomplete supera il costo del prezzo 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 del widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Questo include sia le richieste Place Autocomplete sia la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields
per assicurarti di richiedere solo i campi Dati di base.
Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi i dettagli dei luoghi relativi alla previsione selezionata, includi i seguenti parametri:
- L'ID luogo della risposta di Place Autocomplete.
- Il token di sessione utilizzato nella richiesta Place Autocomplete
- Il parametro
fields
che specifica i campi Dati di base come indirizzo e geometria
Valuta la possibilità di ritardare le richieste di Place Autocomplete
Puoi adottare strategie come il ritardo di una richiesta Place Autocomplete finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che la tua applicazione effettui meno richieste. Ad esempio, effettuare richieste di Place Autocomplete per ogni carattere dopo che l'utente ha digitato il terzo carattere significa che se l'utente digita sette caratteri e poi seleziona una previsione per cui effettui una richiesta API Geocoding, il costo totale sarà di 0,01632 $ (4 * 0,00283 $ di completamento automatico per richiesta + 0,005 $di geocodifica).1
Se il ritardo delle richieste può ridurre la richiesta programmatica media a meno di quattro, puoi seguire le indicazioni per l'implementazione di Autocompletamento dei luoghi efficiente con l'API Geocoding. Tieni presente che le richieste ritardate possono essere percepite come latenza dall'utente che potrebbe aspettarsi di vedere le previsioni a ogni nuova sequenza di tasti.
Valuta la possibilità di utilizzare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con meno caratteri.
-
I costi indicati qui sono in dollari statunitensi. Per informazioni complete sui prezzi, consulta la pagina Fatturazione di Google Maps Platform.
Best practice per le prestazioni
Le seguenti linee guida descrivono i modi per ottimizzare il rendimento di Ricerca automatica dei luoghi:
- Aggiungi limitazioni in base al paese. differenziazione per località, e (per le implementazioni di pubblicità programmatica) la preferenza della lingua per Place Autocomplete implementazione. La preferenza della lingua non è necessaria con widget perché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
- Se Place Autocomplete è accompagnato da una mappa, puoi differenziare la posizione in base all'area visibile della mappa.
- Quando un utente non sceglie una delle previsioni del completamento automatico, in genere perché nessuna di queste corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
- Se prevedi che l'utente inserisca solo i dati dell'indirizzo, riutilizza i dati inseriti dall'utente in una chiamata all'API Geocoding.
- Se prevedi che l'utente inserisca query per un luogo specifico tramite il nome o l'indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in una regione specifica, utilizza la sbiasatura della località.
- Utenti che inseriscono indirizzi di proprietà secondarie in paesi in cui il supporto del completamento automatico dei luoghi per gli indirizzi di proprietà secondarie è incompleto, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" genera una previsione parziale in Posizione completamento automatico.
- Utenti che inseriscono indirizzi con prefissi di tratti stradali come "23-30 29th St, Queens" a New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai nelle Hawaii.
Limiti e norme di utilizzo
Quote
Per informazioni su quote e prezzi, consulta Documentazione su utilizzo e fatturazione per l'API Places.
Norme
L'utilizzo dell'API Places Library, Maps JavaScript deve essere conforme ai norme descritte per l'API Places.