Introduzione
Il completamento automatico è una funzione della libreria di Places API Maps JavaScript. Puoi usare il completamento automatico per il comportamento type-ahead-search 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ù codici. Le applicazioni possono quindi inviare query mentre l'utente digita, fornire previsioni immediate sui luoghi. Come definito dall'API Places, un "luogo" può essere un'azienda, una posizione geografica o un punto d'interesse.
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 lo stato Scheda Raccolta. In alternativa, dal menu laterale a sinistra, Seleziona Libreria.
- Cerca API Places e selezionala dalla dei risultati di ricerca.
- Seleziona ABILITA. Al termine del processo, L'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 la funzionalità contenuta
all'interno di questa libreria, devi prima caricarla utilizzando l'libraries
nell'URL del 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>
Consulta Panoramica delle librerie.
Riepilogo dei corsi
L'API offre due tipi di widget di completamento automatico, che puoi aggiungere tramite
rispettivamente 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 l'inserimento di caratteri. Man mano che l'utente inserisce il testo, il completamento automatico restituisce previsioni sui luoghi sotto forma di elenco a discesa. Quando l'utente seleziona un luogo dall'elenco, le informazioni sul luogo viene restituito all'oggetto con completamento automatico e può essere recuperato dalla tua applicazione. Consulta i dettagli di seguito.Figura 1: campo di testo e elenco di selezione a completamento automatico Figura 2: modulo dell'indirizzo compilato -
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. Forniture per
SearchBox
un elenco esteso di previsioni, che possono includere luoghi (come definito l'API Places) oltre ai termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza nuova", l'elenco di selezione può includere la frase "pizza a Roma" nonché i nomi delle varie pizze prese di corrente. SearchBox
offre meno opzioni rispettoAutocomplete
per limitare la ricerca. Nel primo caso, può differenziare la ricerca verso un determinatoLatLngBounds
. Nella In secondo luogo, puoi limitare la ricerca a un determinato paese e a un tipi di luogo e impostarne i limiti. Per ulteriori informazioni, vedi di seguito.
Figura 3: una casella di ricerca presenta termini di ricerca e previsioni sui luoghi. - La differenza principale sta nel fatto che
i risultati visualizzati nell'elenco di selezione. Forniture per
- Puoi creare un nuovo
Oggetto
AutocompleteService
da 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 sopra riportati 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. Consulta le 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
. Questo è il campo di immissione del completamento automatico monitora e collega i risultati. - Un elemento facoltativo
AutocompleteOptions
, che può essere usato contengono 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 visualizzati tutti i tipi restituito. bounds
è un oggettogoogle.maps.LatLngBounds
che specifica l'area in cui cercare i luoghi. I risultati sono differenziati (ma non limitati a) 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.- È possibile utilizzare
componentRestrictions
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 che stai utilizzando un codice che include i paesi, i territori dipendenti e le aree di interesse geografico da te indicate. Puoi trovare informazioni sul codice all'indirizzo Wikipedia: elenco ISO Codici paese 3166 o ISO per la navigazione online Piattaforma.
- È possibile usare
placeIdOnly
per indicareAutocomplete
per 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, Place Autocomplete presenta tutti i tipi di luogo, con parziali per le previsioni in prossimità del posizione dell'utente e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta luogo Opzioni di completamento automatico per presentare previsioni più pertinenti in base a il 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 il parametro
Opzioni bounds
, componentRestrictions
e types
per
richiedere luoghi di tipo establishment
, privilegiando quelli all'interno dell'area geografica specificata
e limitando le previsioni ai soli luoghi degli Stati Uniti. L'impostazione del parametro
L'opzione fields
specifica le informazioni da restituire in merito al 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
nel
AutocompleteOptions
che vengono passate al costruttore del widget, come dimostrato nella precedente
ad esempio, o richiama 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 sull'area visibile della mappa.
- Limita la ricerca ai limiti.
- Limita la ricerca a un paese specifico.
L'esempio precedente mostra l'impostazione dei 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 sull'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 scollegare 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"], });
Limita tipi di luogo
Usa l'opzione types
o chiama il numero setTypes()
per applicare vincoli
per determinati tipi di luoghi. Questo vincolo specifica un tipo o una raccolta di tipi,
come indicato 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 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 nella tabella 3.
La richiesta verrà rifiutata se:
- Puoi specificare più di cinque tipi.
- Specifichi tipi non riconosciuti.
- Puoi mescolare qualsiasi tipo dalla Tabella 1 o la Tabella 2 con qualsiasi filtro dalla Tabella 3.
La demo di Places Autocomplete mostra le differenze nelle previsioni tra diversi tipi di luogo.
Recupero delle informazioni sul luogo in corso...
Quando un utente seleziona un luogo dalle previsioni allegate al completamento automatico.
campo di testo, il servizio attiva un evento place_changed
. Per trovare un luogo
dettagli:
- 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 tutte le
disponibili per il luogo selezionato e ti verrà addebitato l'importo corrispondente.
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 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ù sulle
description
in
Luoghi
documentazione del completamento automatico.
Per i moduli indirizzo, è utile ottenere l'indirizzo in un formato strutturato. A
restituisce l'indirizzo strutturato per il luogo selezionato, chiama
Autocomplete.setFields()
e specificare 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 sul modo in cui Google Maps L'API JavaScript sceglie il linguaggio da utilizzare, consulta la documentazione su localizzazione.
Per personalizzare l'aspetto del widget, vedi Applicare uno stile ai widget Completamento automatico e SearchBox.
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 allegare SearchBox
a un campo di testo e, come
testo inserito, il servizio restituirà previsioni nel
di un elenco 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 in new", l'elenco di selezione può
includi la frase "pizza a New York, NY" nonché i nomi di vari
pizzerie. 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
. Questo è il campo di immissione che il servizioSearchBox
monitorerà e a cui associa 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 all'interno 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.
Recupero delle informazioni sul luogo in corso...
Quando l'utente seleziona un elemento dalle previsioni allegate alla 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
risultati di Place Details.
TypeScript
// Listen for the event fired when the user selects a prediction and retrieve // more details for that place. searchBox.addListener("places_changed", () => { 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, vedi Applicare uno stile ai widget Completamento automatico e SearchBox.
Recupero delle previsioni di Place Autocomplete Service in modo programmatico
Per recuperare le previsioni in modo programmatico, utilizza
AutocompleteService
. AutocompleteService
non aggiunge alcun controllo UI. Restituisce invece un array di previsioni
oggetti contenenti il testo della previsione, le informazioni di riferimento
e i dettagli di come il risultato corrisponde all'input dell'utente.
Ciò è utile se desideri un maggiore controllo sull'interfaccia utente rispetto a
offerto da Autocomplete
e SearchBox
descritti sopra.
AutocompleteService
espone i seguenti metodi:
getPlacePredictions()
restituisce le previsioni sui luoghi. Nota: un "luogo" può essere un'attività, una posizione geografica punto d'interesse, 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 nuova", l'elenco di selezione può includere la frase "pizza a Roma" nonché i nomi delle varie pizzerie.
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 mettendo in evidenza le sottostringhe nell'applicazione. In molti casi, verrà visualizzata come sottostringa del campo 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 elementi della query. Per luogo, ogni elemento costituirà in genere una parte dell'indirizzo.offset
è l'offset dei caratteri, misurato dal inizio della stringa di descrizione, in corrispondenza della quale 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()
è possibile utilizzare i token di sessione (se implementati) per raggruppare le richieste di completamento automatico per la fatturazione
scopi. I token di sessione raggruppano le fasi di query e selezione di un utente
la ricerca con completamento automatico in una sessione discreta ai fini della 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.
Una volta terminata la 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 creare un singolo
Dettagli del luogo
relativa al luogo risultante da una chiamata a AutocompleteService.getPlacePredictions()
.
In questo caso, la richiesta di completamento automatico viene combinata con Place Details
che viene addebitata come normale richiesta Place Details. Non è previsto alcun costo per
richiesta di completamento automatico.
Assicurati di trasmettere un token di sessione univoco per ogni nuova sessione. Utilizzare lo stesso token per più di una sessione di completamento automatico invaliderà quelle sessioni di completamento automatico e tutte le richieste di completamento automatico in sessioni non valide saranno addebitate singolarmente utilizzando il completamento automatico Per richiesta di SKU. Scopri di più sui token di sessione.
L'esempio seguente mostra la creazione di un token di sessione e la sua trasmissione in una
AutocompleteService
(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. 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 UI forniti da Autocomplete
e
SearchBox
sono pensati per essere inclusi in una mappa di Google. Potresti volere
per adattarne lo stile al tuo sito. Le seguenti classi CSS sono
disponibili. Tutti i corsi elencati di seguito si applicano sia ai
Autocomplete
e i widget SearchBox
.
![Illustrazione grafica delle classi CSS per Autocomplete e
Widget SearchBox](https://developers.google.cn/static/maps/documentation/javascript/images/place-autocomplete-css-diagram.png?authuser=8&hl=it)
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 vi passa sopra il puntatore del mouse. |
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 è la parte principale di
la previsione. Per le posizioni geografiche, contiene il nome di un luogo,
"Sydney", oppure il nome e il numero civico, ad esempio "Via Roma 10". Per
ricerche basate su testo come "pizza a New York", contiene l'intero
della query. Per impostazione predefinita, pac-item-query è colorato
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. Di
Per impostazione predefinita, il testo corrispondente viene 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 . |
Utilizzare il componente Selettore luogo
Nota: questo esempio utilizza una libreria open source. Consulta le README per ricevere assistenza e feedback relativi alla raccolta.
Prova i componenti web. Utilizza la Componente web Selettore di luoghi per attivare l'inserimento di testo che consente agli utenti finali di cercare un indirizzo o un luogo specifico utilizzando il completamento automatico.
![GIF con casella di ricerca. L'utente inizia a digitare un indirizzo come input e un menu a discesa con
indirizzi IP esterni. L'utente fa clic su un indirizzo dal menu a discesa e la casella di ricerca si riempie
nel resto dell'indirizzo.](https://developers.google.cn/static/maps/documentation/javascript/images/place-picker.gif?authuser=8&hl=it)
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
- Apprendere i concetti di base della funzionalità di completamento automatico dei luoghi campi di dati dall'inizio.
- I campi della differenziazione per località e delle restrizioni di località sono facoltativi ma possono hanno un impatto significativo sulle prestazioni 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 i casi in cui non è possibile effettuare selezioni e che 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 di Place Autocomplete utilizza le maschere dei campi nei widget Place Details e Place Autocomplete per restituire solo campi di 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 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 richiesta richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?
Sì, sono necessari ulteriori dettagli
Utilizza Place Autocomplete 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, 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 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 avere la certezza di richiedere solo il parametro
campi di dati del luogo necessari.
Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi Place Details (Dettagli luogo) per la 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 l'indirizzo e la posizione
L'API Geocoding potrebbe essere un'opzione più conveniente rispetto a Place Details per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete. L'efficienza del completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti accedono, di dove viene utilizzata l'applicazione e dell'implementazione o meno di best practice per l'ottimizzazione delle prestazioni.
Per rispondere alla seguente domanda, analizza quanti caratteri vengono digitati in media da un utente prima di selezionare una previsione di Place Autocomplete nella tua applicazione.
I tuoi utenti selezionano una previsione di completamento automatico del luogo in media in quattro 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 invia indirizzi e coordinate di latitudine/longitudine a 0,005 $per richiesta. Effettuare quattro richieste Place Autocomplete - Per Request costa $0,01132, pertanto il costo totale di quattro richieste più una chiamata API Geocoding per la previsione del luogo selezionato sarà di $0,01632, inferiore al prezzo di Per Session Autocomplete di $0,017 per sessione.1
Valuta la possibilità di adottare le best practice sul rendimento per consentire ai tuoi utenti di ottenere la previsione che cercano con ancora meno 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 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 luogo) per la 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 le richieste ritardate possono portare la tua richiesta di pubblicità programmatica media al di sotto di quattro, puoi seguire le indicazioni per l'implementazione del completamento automatico di Place Autocomplete 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 adottare le best practice sul rendimento per consentire agli utenti di ottenere la previsione 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 le prestazioni
Le seguenti linee guida descrivono i modi per ottimizzare le prestazioni di Place Autocomplete:
- 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.
- Nei casi in cui un utente non sceglie una delle previsioni di Completamento automatico, in genere
poiché nessuna di queste previsioni corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare
input utente per tentare di ottenere risultati più pertinenti:
- Se prevedi che l'utente inserisca solo informazioni relative all'indirizzo, riutilizza l'input dell'utente originale 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 differenziazione per località.
- Utenti che inseriscono indirizzi di locali secondari nei paesi in cui Place Autocomplete supporta gli indirizzi secondari sono incompleti, ad esempio Cechia, Estonia e Lituania. Ad esempio, Indirizzo in ceco "Stroupežnického 3191/17, Praha" genera una previsione parziale in Place Completamento automatico.
- Utenti che inseriscono indirizzi con prefissi di segmenti di strada come "23-30 29th St, Queens" nel 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 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.