Place Autocomplete

Seleziona la piattaforma: Android iOS JavaScript Web Service

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:

  1. Vai alla sezione Console Google Cloud.
  2. 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.
  3. Nell'elenco delle API sulla Dashboard, cerca API Places.
  4. Se vedi l'API nell'elenco, non devi eseguire altre operazioni. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Raccolta. In alternativa, nel menu a sinistra, seleziona Raccolta.
    2. Cerca API Places e selezionala dall'elenco dei risultati.
    3. 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.
    Un campo di testo di completamento automatico e l&#39;elenco di suggerimenti di luoghi fornito quando l&#39;utente inserisce la query di ricerca.
    Figura 1: campo di testo e elenco di selezione a completamento automatico
    Un modulo per l&#39;indirizzo compilato.
    Figura 2: modulo dell'indirizzo compilato
  • SearchBox aggiunge un campo di immissione di testo alla tua pagina web, allo stesso modo di Autocomplete. 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 a Autocomplete per limitare la ricerca. Nel primo caso, può differenziare la ricerca verso un determinato LatLngBounds. 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.
    Un modulo per l&#39;indirizzo compilato.
    Figura 3: una casella di ricerca presenta termini di ricerca e previsioni sui luoghi.
    Consulta i dettagli di seguito.
  • Puoi creare un oggetto AutocompleteService per recuperare le previsioni in modo programmatico. Chiama getPlacePredictions() per recupera luoghi corrispondenti o chiama getQueryPredictions() 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 tipo text. 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 risposta Place Details per il valore PlaceResult 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, vedi PlaceResult.
    • Un array di types che specifica un tipo esplicito o una raccolta di tipi, come elencato nei tipi supportati. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi.
    • bounds è un oggetto google.maps.LatLngBounds che specifica l'area in cui cercare i luoghi. I risultati sono orientati verso, ma non limitati a, i luoghi contenuti all'interno di questi limiti.
    • strictBounds è un boolean che specifica se l'API deve restituire solo i luoghi che si trovano strettamente all'interno della regione definita da bounds 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 lingua componentRestrictions 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 widget Autocomplete di recuperare solo gli ID luogo. Chiamata in corso getPlace() sull'oggetto Autocomplete, PlaceResult reso disponibile avrà solo place id, Proprietà types e name impostate. Puoi utilizzare il valore restituito ID luogo con chiamate a Places, Geocoding, Directions o Distance Matrix i servizi di machine learning.

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);
index.ts

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);

index.js

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);
index.ts

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);

index.js
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);
index.ts

JavaScript

autocomplete.bindTo("bounds", map);

index.js

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 });
index.ts

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });
index.js

Visualizza esempio

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"],
});
index.ts

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

index.js

Visualizza esempio

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.

Visita la demo

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:

  1. Crea un gestore di eventi per l'evento place_changed e richiama addListener() sull'oggetto Autocomplete per aggiungere il gestore.
  2. Chiama il numero Autocomplete.getPlace() sull'oggetto Autocomplete, per recuperare un PlaceResult 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();
}
index.ts

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;

index.js

Visualizza esempio

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.

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 tipo text. Si tratta del campo di immissione che il servizio SearchBox monitorerà e a cui agganciare i risultati.
  • Un argomento options, che può contenere Proprietà bounds: bounds è un google.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.

Visualizza esempio

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);
});
index.ts

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);
});
index.js

Visualizza esempio

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 SearchBoxdescritti 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 valore AutocompletionRequest.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 campo placeId 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;
index.ts

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;
index.js

CSS

style.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>
index.html

Prova Sample

Visualizza esempio

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.

Un&#39;illustrazione grafica delle classi CSS per i widget di completamento automatico e della casella di ricerca
Classi CSS per i widget di completamento automatico e di casella di ricerca
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.
Per assistenza nella scelta dell'implementazione di Completamento automatico dei luoghi più adatta alle tue esigenze, seleziona la scheda corrispondente alla tua risposta alla seguente domanda.

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:

  1. L'ID luogo della risposta di Place Autocomplete
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  3. 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:

  1. L'ID luogo della risposta di Place Autocomplete.
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  3. 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.

  1. 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à.
    Altri scenari in cui è meglio eseguire il fallback all'API Geocoding includono:
    • 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.