Place Autocomplete

Seleziona piattaforma: Android iOS JavaScript Servizio web

Introduzione

Il completamento automatico è una funzionalità della libreria Places dell'API Maps JavaScript. Puoi utilizzare la funzionalità di completamento automatico per assegnare alle tue applicazioni il comportamento di ricerca iniziale del campo di ricerca di Google Maps. Il servizio di completamento automatico può corrispondere a parole e sottostringhe complete, risolvendo nomi di luoghi, indirizzi e plus code. Le applicazioni possono quindi inviare query come tipi di utente per fornire previsioni immediate sui luoghi.

Per cominciare

Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia abilitata in Google Cloud Console, nello stesso progetto configurato per l'API Maps JavaScript.

Per visualizzare l'elenco delle API abilitate:

  1. Vai a Google Cloud Console.
  2. Fai clic sul pulsante Seleziona un progetto, quindi scegli lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API nella Dashboard, cerca API Places.
  4. Se vedi l'API nell'elenco, non devi fare altro. Se l'API non è elencata, abilitala:
    1. Nella parte superiore della pagina, seleziona ABILITA API per visualizzare la scheda Libreria. In alternativa, seleziona Raccolta dal menu laterale a sinistra.
    2. Cerca l'API Places, quindi selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine della procedura, l'API Places viene visualizzata nell'elenco delle API sulla Dashboard.

Caricamento della raccolta in corso...

Il servizio Places è una libreria autonoma, separata dal codice principale dell'API Maps JavaScript. Per utilizzare la funzionalità contenuta in questa libreria, devi prima caricarla utilizzando il parametro libraries nell'URL di bootstrap dell'API di Google Maps:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Per maggiori informazioni, consulta la 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 Riferimento API JavaScript di Maps: Classe AutocompleteService).

Ecco un riepilogo dei corsi disponibili:

  • Autocomplete aggiunge un campo di testo alla pagina web e monitora tale campo per individuare i caratteri. Man mano che l'utente inserisce un testo, il completamento automatico restituisce le previsioni dei 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 con completamento automatico e l&#39;elenco di selezione delle previsioni dei luoghi fornite quando l&#39;utente inserisce la query di ricerca.
    Figura 1: campo di testo per il completamento automatico e elenco di selezione
    Un modulo di indirizzo compilato.
    Figura 2: modulo Indirizzi compilato
  • SearchBox aggiunge un campo di immissione testo alla tua pagina web, proprio come accade per Autocomplete. Le differenze sono le seguenti:
    • La differenza principale sta nei risultati visualizzati nell'elenco di selezione. SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) oltre a termini di ricerca suggeriti. Ad esempio, se l'utente inserisce 'pizza in nuovo', l'elenco di prelievi può includere la frase 'pizza a New York, NY' nonché i nomi dei vari punti vendita di pizza.
    • SearchBox offre meno opzioni rispetto a Autocomplete per limitare la ricerca. Nel primo caso, puoi bias la ricerca verso un determinato LatLngBounds. In quest'ultimo caso, puoi limitare la ricerca a un determinato paese e a determinati tipi di luoghi, oltre a impostare i limiti. Per saperne di più, consulta sotto.
    Un modulo di indirizzo compilato.
    Figura 3: una casella di ricerca presenta i termini di ricerca e le previsioni dei luoghi.
    Vedi i dettagli di seguito.
  • Puoi creare un oggetto AutocompleteService per recuperare le previsioni in modo programmatico. Chiama getPlacePredictions() per recuperare i luoghi corrispondenti oppure chiama getQueryPredictions() per recuperare i luoghi corrispondenti più i termini di ricerca suggeriti. Nota: AutocompleteService non aggiunge alcun controllo UI. I metodi precedenti restituiscono invece un array di oggetti di previsione. Ogni oggetto di previsione contiene il testo della previsione, informazioni di riferimento e dettagli sul modo in cui il risultato corrisponde all'input utente. Consulta i dettagli di seguito.

Aggiungere un widget Completamento automatico

Il widget Autocomplete crea un campo di immissione di testo sulla pagina web, fornisce previsioni dei luoghi in un elenco di opzioni UI e restituisce i dettagli del luogo in risposta a una richiesta getPlace(). Ogni voce nell'elenco di selezione corrisponde a una singola posizione (come definita dall'API Places).

Il costruttore Autocomplete prende due argomenti:

  • Un elemento HTML input di tipo text. Si tratta del campo di immissione che il servizio di completamento automatico monitorerà e allega i risultati.
  • Un argomento AutocompleteOptions facoltativo, che può contenere le seguenti proprietà:
    • Un array di dati fields da includere nella risposta Place Details per l'utente selezionato PlaceResult. Se la proprietà non è impostata o se viene trasmesso ['ALL'], tutti i campi disponibili vengono restituiti e fatturati per (opzione sconsigliata per i deployment di produzione). Per un elenco dei campi, consulta la sezione PlaceResult.
    • Un array di types che specifica un tipo esplicito o una raccolta di tipi, come indicato 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, ma non limitatamente, ai luoghi contenuti in questi limiti.
    • strictBounds è un boolean che specifica se l'API deve restituire soltanto i luoghi che si trovano all'interno dell'area geografica definita dal valore bounds specificato. L'API non restituisce risultati al di fuori di questa area geografica anche se corrispondono all'input utente.
    • componentRestrictions può essere utilizzato per limitare i risultati a gruppi specifici. Attualmente, puoi utilizzare componentRestrictions per filtrare in base a un massimo di 5 paesi. I paesi devono essere trasmessi come codice paese compatibile con ISO 3166-1 Alpha-2 a due caratteri. Più paesi devono essere trasmessi come un elenco di codici paese.

      Nota: se ricevi risultati imprevisti con un codice paese, verifica di utilizzare un codice che includa paesi, territori dipendenti e aree speciali di interesse geografico che vuoi. Puoi trovare informazioni sul codice su Wikipedia: elenco dei codici paese ISO 3166 o sulla piattaforma di navigazione online ISO.

    • placeIdOnly può essere utilizzato per indicare al widget Autocomplete di recuperare solo gli ID luogo. Per la chiamata getPlace() all'oggetto Autocomplete, PlaceResult messo a disposizione avrà solo le proprietà place id, types e name impostate. Puoi utilizzare l'ID luogo restituito con le chiamate ai servizi Luoghi, Geocodifica, Indicazioni stradali o Matrice della distanza.

Limitazioni di completamento automatico vincolanti

Per impostazione predefinita, la funzionalità di completamento automatico del luogo presenta tutti i tipi di luogo, polarizzato per le previsioni vicino alla posizione dell'utente e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta le opzioni di Completamento automatico per presentare previsioni più pertinenti in base al tuo caso d'uso.

Imposta le opzioni al momento della realizzazione

Il costruttore Autocomplete accetta un parametro AutocompleteOptions per impostare vincoli al momento della creazione del widget. L'esempio riportato di seguito consente di impostare le opzioni bounds, componentRestrictions e types per richiedere i luoghi di tipo establishment, privilegiando quelli all'interno dell'area geografica specificata e limitando le previsioni solo alle località all'interno degli Stati Uniti. L'impostazione fields consente di specificare le informazioni da restituire in merito al luogo selezionato dell'utente.

Chiama setOptions() per modificare il valore di un'opzione relativa a 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,
  types: ["establishment"],
};

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,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Specificare i campi di dati

Specifica i campi dati per evitare che ti vengano addebitati SKU di dati dei luoghi di cui non hai bisogno. Includi la proprietà fields nel AutocompleteOptions che viene passato 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 limiti dell'area di ricerca per il completamento automatico

Puoi bias i risultati del completamento automatico per preferire una posizione o un'area approssimativa, nei seguenti modi:

  • Imposta i limiti relativi alla 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 mostrano le altre tecniche di bias.

Modificare i limiti di un completamento automatico esistente

Chiama setBounds() per impostare l'area di ricerca su un Autocomplete esistente in limiti rettangolari.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Imposta i limiti per l'area visibile della mappa

Utilizza bindTo() per eseguire il bias dei risultati nell'area visibile della mappa, anche quando l'area visibile cambia.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Utilizza unbind() per annullare l'associazione delle previsioni di completamento automatico dalla visualizzazione 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 });

Visualizza l'esempio

Limita la ricerca ai limiti correnti

Imposta l'opzione strictBounds per limitare i risultati ai limiti attuali, in base alla visualizzazione della mappa o ai limiti rettangolari.

autocomplete.setOptions({ strictBounds: true });
Limitare le previsioni a un paese specifico

Utilizza l'opzione componentRestrictions o chiama setComponentRestrictions() per limitare la ricerca di completamento automatico a un insieme specifico di un massimo di cinque paesi.

TypeScript

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

JavaScript

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

Visualizza l'esempio

Limita i tipi di luogo

Utilizza l'opzione types o chiama setTypes() per vincolare le previsioni a determinati tipi di luoghi. Questo vincolo specifica un tipo o una raccolta di tipi, come elencato nei tipi di luogo. Se non viene specificato alcun vincolo, vengono restituiti tutti i tipi.

Per il valore dell'opzione types o il valore trasmesso a setTypes(), puoi specificare:

  • Un array contenente fino a cinque valori della Tabella 1 o della Tabella 2 dei Tipi di luogo. Ad esempio:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    Oppure:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Qualsiasi filtro nella Tabella 3 di Tipi di luogo. Puoi specificare un solo valore dalla tabella 3.

La richiesta sarà rifiutata se:

  • Specifica più di cinque tipi.
  • Specifica eventuali tipi non riconosciuti.
  • Puoi combinare qualsiasi tipo di Tabella 1 o Tabella 2 con qualsiasi filtro della Tabella 3.

La demo di Luoghi con completamento automatico mostra le differenze di previsioni tra i diversi tipi di luoghi.

Visita la demo

Recupero informazioni sul luogo

Quando un utente seleziona un luogo dalle previsioni allegate al campo di testo di completamento automatico, il servizio attiva un evento place_changed. Per ottenere i dettagli del luogo:

  1. Crea un gestore di eventi per l'evento place_changed e chiama addListener() sull'oggetto Autocomplete per aggiungere il gestore.
  2. Richiama Autocomplete.getPlace() l'oggetto Autocomplete per recuperare un oggetto PlaceResult, che potrai utilizzare per ottenere ulteriori informazioni sul luogo selezionato.

Per impostazione predefinita, quando un utente seleziona un luogo, il completamento automatico restituisce tutti i campi di dati disponibili per il luogo selezionato e i dati verranno addebitati di conseguenza. Utilizza Autocomplete.setFields() per specificare i campi di dati dei luoghi da restituire. Scopri di più sull'oggetto PlaceResult, tra cui un elenco di campi di dati dei luoghi che puoi richiedere. Per evitare di pagare dati che non ti servono, assicurati di utilizzare Autocomplete.setFields() per specificare solo i dati dei luoghi che utilizzerai.

La proprietà name contiene la proprietà description delle previsioni di completamento automatico di Places. Per scoprire di più su description, consulta la documentazione di completamento automatico di Places.

Per i moduli dell'indirizzo, è utile recuperare l'indirizzo in formato strutturato. Per restituire l'indirizzo strutturato per il luogo selezionato, chiama Autocomplete.setFields() e specifica il campo address_components.

L'esempio seguente utilizza il completamento automatico per compilare i campi nel modulo indirizzo.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Visualizza l'esempio

Personalizzare il testo segnaposto

Per impostazione predefinita, il campo di testo creato dal servizio di completamento automatico contiene testo segnaposto standard. Per modificare il testo, imposta l'attributo placeholder nell'elemento input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Nota: il testo segnaposto predefinito viene localizzato automaticamente. Se specifichi il tuo valore segnaposto, devi gestire la localizzazione di tale valore nell'applicazione. Per informazioni su come l'API Google Maps JavaScript sceglie la lingua da utilizzare, leggi la documentazione sulla localizzazione.

Per personalizzare l'aspetto del widget, consulta l'articolo Utilizzo dei widget Completamento automatico e SearchBox.

Il SearchBox consente agli utenti di eseguire una ricerca geografica basata su testo, ad esempio 'pizza a New York' o 'scarpe da negozi vicino a Robson Street'. Puoi collegare SearchBox a un campo di testo e, man mano che inserisci il testo, il servizio restituirà previsioni sotto forma di elenco a discesa.

SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) oltre a termini di ricerca suggeriti. Ad esempio, se l'utente inserisce 'pizza in nuovo', l'elenco di scelta può includere la frase 'pizza a New York, NY' così come i nomi di vari locali di pizza. Quando un utente seleziona un luogo dall'elenco, le informazioni su quel luogo vengono restituite all'oggetto SearchBox e possono essere recuperate dalla tua applicazione.

Il costruttore SearchBox prende due argomenti:

  • Un elemento HTML input di tipo text. Questo è il campo di immissione che il servizio SearchBox monitorerà e allega i risultati.
  • Un argomento options, che può contenere la proprietà bounds: bounds è un oggetto google.maps.LatLngBounds che specifica l'area in cui cercare i luoghi. I risultati sono orientati, ma non limitatamente, ai luoghi contenuti in questi limiti.

Il seguente codice utilizza il parametro limiti per eseguire il bias dei risultati in base a luoghi all'interno di una particolare area geografica, specificati tramite coordinate di latitudine/longitudine.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Modificare l'area di ricerca di SearchBox

Per modificare l'area di ricerca di un SearchBox esistente, chiama setBounds() sull'oggetto SearchBox e trasmetti l'oggetto LatLngBounds pertinente.

Visualizza l'esempio

Recupero informazioni sul luogo

Quando l'utente seleziona un elemento dalle previsioni allegate alla casella di ricerca, il servizio attiva un evento places_changed. Puoi chiamare getPlaces() nell'oggetto SearchBox per recuperare un array contenente diverse previsioni, ciascuna delle quali è un oggetto PlaceResult.

Per scoprire di più sull'oggetto PlaceResult, consulta la documentazione sui risultati dei dettagli del luogo.

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

Visualizza l'esempio

Per personalizzare l'aspetto del widget, consulta l'articolo Utilizzo dei widget Completamento automatico e SearchBox.

Recupero programmatico di previsioni di completamento automatico di luoghi

Per recuperare le previsioni in modo programmatico, utilizza la classe AutocompleteService. AutocompleteService non aggiunge alcun controllo UI. ma restituisce un array di oggetti di previsione, ciascuno con il testo della previsione, informazioni di riferimento e dettagli sul modo in cui il risultato corrisponde all'input utente. Questo è utile se vuoi avere un maggiore controllo sull'interfaccia utente rispetto a quanto offerto da Autocomplete e SearchBox descritti sopra.

AutocompleteService espone i seguenti metodi:

  • getPlacePredictions() restituisce le previsioni dei luoghi. Nota: un 'luogo' può essere un'azienda, una posizione geografica o un punto di interesse evidente, come definito dall'API Places.
  • getQueryPredictions() restituisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) oltre a termini di ricerca suggeriti. Ad esempio, se l'utente inserisce 'pizza in nuovo', l'elenco di scelta può includere la frase 'pizza a New York, NY' nonché i nomi dei vari locali di pizza.

Entrambi i metodi precedenti restituiscono un array di oggetti di previsione nel seguente formato:

  • description è la previsione con corrispondenza.
  • distance_meters è la distanza in metri del luogo dall'elemento AutocompletionRequest.origin specificato.
  • matched_substrings contiene un set di sottostringhe nella descrizione che corrispondono agli elementi nell'input dell'utente. Ciò è utile per evidenziare tali sottostringhe nell'applicazione. In molti casi, la query viene visualizzata come sottostringa del campo della descrizione.
    • length è la lunghezza della sottostringa.
    • offset è l'offset del carattere, misurato dall'inizio della stringa di descrizione in cui viene visualizzata la sottostringa corrispondente.
  • place_id è un identificatore testuale che identifica in modo univoco un luogo. Per recuperare le informazioni sul luogo, passa questo identificatore nel campo placeId di una richiesta Dettagli luogo. Scopri di più su come fare riferimento a un luogo con un ID luogo.
  • terms è un array contenente elementi della query. In genere, per un luogo, ogni elemento costituirà una parte dell'indirizzo.
    • offset è l'offset del carattere, misurato dall'inizio della stringa di descrizione in cui viene visualizzata la sottostringa corrispondente.
    • value è il termine corrispondente.

L'esempio seguente esegue una richiesta di previsione per la frase 'pizza vicino&&;39; mostra il risultato in un elenco.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <script src="https://polyfill.io/v3/polyfill.min.js?features=default"></script>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
     The `defer` attribute causes the callback to execute after the full HTML
     document has been parsed. For non-blocking uses, avoiding race conditions,
     and consistent behavior across browsers, consider loading using Promises
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Prova Esempio

Visualizza l'esempio

Token di sessione

AutocompleteService.getPlacePredictions() utilizza i token di sessione 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 completata dall'utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e si conclude quando seleziona un luogo. Ogni sessione può avere più query, seguite da una selezione di un luogo. Una volta terminata 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 per tutte le sessioni di completamento automatico. Se il parametro sessionToken viene omesso o se riutilizzi un token di sessione, l'addebito per la sessione viene eseguito come se non fosse stato fornito alcun token di sessione (ogni richiesta viene fatturata separatamente).

Puoi utilizzare lo stesso token di sessione per effettuare una singola richiesta Dettagli luogo per il luogo risultante da una chiamata a AutocompleteService.getPlacePredictions(). In questo caso, la richiesta di completamento automatico viene combinata con la richiesta Dettagli luogo e la chiamata viene addebitata come una normale richiesta. Non è previsto alcun costo per la richiesta di completamento automatico.

Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più di una sessione di completamento automatico invaliderà tali sessioni. Inoltre, tutte le richieste di completamento automatico nelle sessioni non valide verranno addebitate individualmente utilizzando lo SKU di completamento automatico per richiesta. Scopri di più sui token di sessione.

L'esempio seguente mostra la creazione di un token di sessione e il 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. L'utilizzo dello stesso token per più di una sessione comporterà l'addebito individuale delle richieste.

Scopri di più sui token di sessione.

Stili dei widget Autocomplete e SearchBox

Per impostazione predefinita, lo stile degli elementi UI forniti da Autocomplete e SearchBox viene inserito in una mappa di Google. Ti consigliamo di modificare lo stile per adattarlo al tuo sito. Sono disponibili le seguenti classi CSS. Tutte le classi elencate di seguito si applicano sia ai widget Autocomplete sia a SearchBox.

Illustrazione grafica delle classi CSS per i widget Autocomplete e SearchBox
Classi CSS per i widget Autocomplete e SearchBox
Classe CSS Descrizione
pac-container L'elemento visivo contenente l'elenco delle previsioni restituite dal servizio di completamento automatico del luogo. Questo elenco viene visualizzato come elenco a discesa sotto il widget Autocomplete o SearchBox.
pac-icon L'icona visualizzata a sinistra di ogni voce nell'elenco delle previsioni.
pac-item Una voce 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: gli elementi selezionati saranno membri di questo corso e del corso pac-item.
pac-item-query Uno span all'interno di pac-item che costituisce la parte principale della previsione. Per le posizioni geografiche, contiene un nome di un luogo, come 'Sydney', o un nome e numero di via, come '10 King Street'. Per le ricerche basate su testo, ad esempio 'pizza a New York, contiene il testo completo della query. Per impostazione predefinita, il colore di pac-item-query è nero. Se è presente del testo aggiuntivo in pac-item, non appartiene a pac-item-query ed eredita lo stile da pac-item. Per impostazione predefinita è di colore grigio. Il testo aggiuntivo è in genere un indirizzo.
pac-matched La parte della previsione restituita che corrisponde all'input dell'utente. Per impostazione predefinita, il testo corrispondente viene evidenziato in grassetto. Tieni presente che il testo corrispondente potrebbe trovarsi in qualsiasi punto di pac-item. Non fa necessariamente parte di pac-item-query e potrebbe essere in parte all'interno di pac-item-query e in parte nel testo rimanente in pac-item.

Effettua l'ottimizzazione con completamento automatico

Questa sezione descrive le best practice per aiutarti a ottenere il massimo dal servizio di completamento automatico dei luoghi.

Di seguito sono riportate alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare l'API Maps JavaScript widget di completamento automatico, il widget di completamento automatico di Places SDK for Android o il controllo dell'UI di completamento automatico di Places
  • Sviluppa una comprensione dei campi dati di completamento automatico del luogo dall'inizio.
  • I campi di geolocalizzazione e di limitazione della posizione sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che l'app venga ridotta correttamente se l'API restituisce un errore.
  • Assicurati che la tua app gestisca quando non è presente alcuna selezione e offre 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 di completamento automatico del luogo, utilizza le maschere dei campi nei widget Dettagli luogo e Completa automaticamente per restituire solo i campi dati dei luoghi necessari.

Ottimizzazione avanzata dei costi

Valuta l'implementazione programmatica del completamento automatico del luogo per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding sul luogo selezionato anziché sul luogo. I prezzi per richiesta abbinati all'API Geocoding sono più economici rispetto ai prezzi per sessione (basati su sessione) se vengono soddisfatte entrambe le seguenti condizioni:

  • Se hai solo bisogno della latitudine/longitudine o dell'indirizzo del luogo selezionato dell'utente, l'API Geocoding fornisce queste informazioni per meno di una chiamata Dettagli luogo.
  • Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro richieste di previsione di completamento automatico o meno, il prezzo per richiesta potrebbe essere più conveniente rispetto al prezzo per sessione.
Per assistenza nella selezione dell'implementazione del completamento automatico dei luoghi che soddisfa le tue esigenze, seleziona la scheda corrispondente alla tua risposta alla seguente domanda.

La tua applicazione richiede informazioni diverse dall'indirizzo e dalla latitudine/longitudine della previsione selezionata?

Sì, sono necessari ulteriori dettagli

Utilizza il completamento automatico dei luoghi basato sulla sessione con i dettagli del luogo.
Poiché la tua applicazione richiede dettagli sul luogo, come il nome, lo stato dell'attività o l'orario di apertura, l'implementazione del completamento automatico del luogo deve utilizzare un token sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per un costo totale di $0,017 per sessione più SKU di dati di Places in base a quali campi di dati di un luogo richiedi.

Implementazione dei widget
La gestione delle sessioni viene integrata automaticamente nei widget
JavaScript, Android o iOS. Sono incluse sia le richieste di completamento automatico di luogo sia le richieste di dettagli sui luoghi nella 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 di completamento automatico dei luoghi. Quando richiedi Dettagli luogo sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta al completamento automatico del luogo
  2. Il token di sessione utilizzato nella richiesta di completamento automatico del luogo.
  3. Il parametro fields che specifica i campi di dati dei luoghi necessari

No, sono necessari soltanto l'indirizzo e la località

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 di completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti accedono al servizio, dove viene utilizzata e se sono state implementate best practice per l'ottimizzazione delle prestazioni.

Per rispondere alla seguente domanda, analizza il numero di caratteri digitato da un utente in media prima di selezionare una previsione di completamento automatico del luogo nella tua applicazione.

In media, gli utenti selezionano una previsione di completamento automatico di luogo in un massimo di quattro richieste?

Implementa il completamento automatico dei luoghi in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione di luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine per 0,005 $per richiesta. Effettuando quattro richieste di completamento automatico per richiesta, costa 0,01132 $, quindi il costo totale di quattro richieste più una chiamata API di geocodifica sulla previsione di luogo selezionata sarà di 0,01632 $, che è inferiore al prezzo di completamento automatico per sessione di 0,017 $per sessione.1

Valuta la possibilità di utilizzare best practice relative alle prestazioni per aiutare gli utenti a ottenere la previsione che cercano in un numero di caratteri inferiore.

No

Utilizza il completamento automatico dei luoghi basato sulla sessione con i dettagli del luogo.
Poiché il numero medio di richieste che prevedi di effettuare prima che un utente selezioni una previsione di completamento automatico di Place supera il costo dei prezzi per sessione, l'implementazione di Place Autocomplete dovrebbe utilizzare un token di sessione sia per le richieste di completamento automatico di Place che per la richiesta Place Details associata, per un costo totale di $0,017 per sessione.1

Implementazione dei widget
La gestione delle sessioni viene integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste di completamento automatico di luogo sia le richieste di dettagli sui luoghi nella 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 di completamento automatico dei luoghi. Quando richiedi Dettagli luogo sulla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo della risposta al completamento automatico del luogo
  2. Il token di sessione utilizzato nella richiesta di completamento automatico del luogo.
  3. Il parametro fields che specifica i campi Dati di base, come indirizzo e geometria

Valuta la possibilità di ritardare le richieste di completamento automatico di un luogo
Puoi utilizzare strategie quali il ritardo di una richiesta di completamento automatico del luogo finché l'utente non ha digitato i primi tre o quattro caratteri in modo che l'applicazione effettui meno richieste. Ad esempio, inoltrando le richieste di Completamento automatico di ciascun carattere dopo che l'utente ha digitato il terzo carattere, se l'utente digita sette caratteri e poi seleziona una previsione per la quale si esegue una richiesta API Geocoding, il costo totale sarà pari a $0,01632 (4 * $0,00283 Autocomplete Per Request + $0,005 Geocoding).1

Se le richieste in ritardo possono raggiungere una media di richieste di pubblicità programmatica inferiore a quattro, puoi seguire le istruzioni per l'implementazione del completamento automatico dei luoghi con l'API Geocoding. Tieni presente che le richieste in ritardo possono essere percepite come latenza dall'utente e questo può aspettarsi di vedere previsioni a ogni nuova pressione dei tasti.

Valuta la possibilità di utilizzare best practice relative alle prestazioni per aiutare gli utenti a ottenere la previsione che cercano in meno caratteri.


  1. I costi elencati qui sono in dollari statunitensi. Per informazioni complete sui prezzi, consulta la pagina Fatturazione di Google Maps Platform.

Best practice per il rendimento

Le seguenti linee guida descrivono i modi per ottimizzare il rendimento del completamento automatico dei luoghi:

  • Aggiungi le limitazioni in base al paese, la polizza di località e (per le implementazioni programmatiche) la preferenza di lingua all'implementazione del completamento automatico dei luoghi. La preferenza della lingua non è necessaria per i widget perché selezionano le preferenze della lingua dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico del luogo è accompagnato da una mappa, puoi orientare la posizione in base al viewport della mappa.
  • Nei casi in cui un utente non scelga una delle previsioni del completamento automatico, in genere dato che nessuna di queste previsioni corrisponde all'indirizzo del risultato desiderato, puoi riutilizzare l'input utente originale per tentare di ottenere risultati più pertinenti:
    • Se prevedi che l'utente inserirà solo le informazioni sull'indirizzo, riutilizza l'input utente originale durante una chiamata all'API Geocoding.
    • Se prevedi che l'utente inserirà query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in un'area geografica specifica, utilizza la differenziazione dei luoghi.
    Altri scenari in cui è meglio utilizzare l'API Geocoding includono:
    • Utenti che inseriscono indirizzi di premesse in paesi diversi da Australia, Nuova Zelanda o Canada. Ad esempio, l'indirizzo negli Stati Uniti "123 Bowdoin St #456, Boston MA, Stati Uniti" non è supportato dal completamento automatico. (il completamento automatico supporta indirizzi di premesse solo in Australia, Nuova Zelanda e Canada). I formati degli indirizzi supportati in questi tre paesi includono "9/321 Pitt Street, Sydney, New South Wales, Australia"; o "14/19 Langana Avenue, Browns Bay, Auckland, Nuova Zelanda" o "145-112 Renfrew Dr, Markham, Ontario, Canada".
    • Gli utenti che inseriscono indirizzi con prefissi del segmento di strada, ad esempio "23-30 29th St, Queens", a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai, nelle Hawaii.

Limiti e criteri di utilizzo

Quote

Per informazioni sulla quota e sui prezzi, consulta la documentazione relativa all'utilizzo e alla fatturazione per l'API Places.

Criteri

L'utilizzo della libreria di Places deve rispettare le norme descritte per l'API Places.