Place Autocomplete

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Introduzione

Il completamento automatico è una funzionalità della libreria Places dell'API Maps JavaScript. Puoi utilizzare il completamento automatico per assegnare alle tue applicazioni il comportamento di ricerca type-ahead del campo di ricerca di Google Maps. Il servizio di completamento automatico può creare corrispondenze con parole complete e sottostringhe, risolvendo nomi di luoghi, indirizzi e più codici. Le applicazioni possono quindi inviare query come tipo di utente per fornire previsioni immediate sui luoghi.

Per iniziare

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

Per visualizzare l'elenco delle API abilitate:

  1. Vai alla console Google Cloud.
  2. Fai clic sul pulsante Seleziona un progetto, poi seleziona lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Nell'elenco delle API nella dashboard, cerca API Places.
  4. Se vedi l'API nell'elenco, non devi eseguire altre operazioni. Se l'API non è nell'elenco, 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 nella dashboard.

Caricamento della libreria in corso...

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

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

Per ulteriori informazioni, consulta la panoramica delle librerie.

Riepilogo dei corsi

L'API offre due tipi di widget con completamento automatico, che puoi aggiungere rispettivamente tramite le classi Autocomplete e SearchBox. Inoltre, puoi utilizzare la classe AutocompleteService per recuperare i risultati del completamento automatico in modo programmatico (consulta la pagina di riferimento dell'API Maps JavaScript: classe AutocompleteService).

Di seguito è riportato un riepilogo dei corsi disponibili:

  • Autocomplete aggiunge un campo di immissione di testo alla pagina web e monitora questo campo per rilevare i caratteri. Mentre l'utente inserisce il testo, il completamento automatico restituisce le previsioni sotto forma di elenco a discesa. Quando l'utente seleziona un luogo dall'elenco, le informazioni sul luogo vengono restituite all'oggetto di completamento automatico e possono essere recuperate dall'applicazione. Consulta i dettagli di seguito.
    Un campo di testo a 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 con completamento automatico ed elenco di selezione
    Un modulo per l&#39;indirizzo compilato.
    Figura 2: modulo dell'indirizzo completato
  • SearchBox aggiunge un campo di immissione di testo alla pagina web, in modo molto analogo a Autocomplete. Le differenze sono le seguenti:
    • La differenza principale risiede nei risultati che appaiono nell'elenco di selezione. SearchBox fornisce un elenco esteso di previsioni, che può includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza nuova", la lista di selezione potrebbe includere la frase "pizza a Roma a Milano" e i nomi di varie pizzerie.
    • SearchBox offre meno opzioni rispetto a Autocomplete per limitare la ricerca. Nel primo, puoi differenziare la ricerca in base a un determinato LatLngBounds. Nel secondo caso, puoi limitare la ricerca a un paese e a tipi di luogo specifici, nonché impostare i limiti. Per maggiori informazioni, vedi di seguito.
    Un modulo per l&#39;indirizzo compilato.
    Figura 3: una casella di ricerca presenta i termini di ricerca e le previsioni dei luoghi.
    Consulta 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 il numero getQueryPredictions() per recuperare i luoghi corrispondenti insieme ai termini di ricerca suggeriti. Nota: AutocompleteService non aggiunge alcun controllo dell'interfaccia utente. I metodi sopra riportati, invece, restituiscono un array di oggetti di previsione. Ogni oggetto di previsione contiene il testo della previsione, nonché informazioni di riferimento e dettagli di come il risultato corrisponde all'input utente. Consulta i dettagli di seguito.

Aggiunta di un widget Autocomplete

Il widget Autocomplete crea un campo di immissione di testo nella pagina web, fornisce previsioni dei luoghi in un elenco di scelta dell'interfaccia utente e restituisce i dettagli sui luoghi in risposta a una richiesta getPlace(). Ogni voce nell'elenco di selezione corrisponde a una singola posizione (come definita dall'API Places).

Il costruttore Autocomplete accetta due argomenti:

  • Un elemento HTML input di tipo text. Questo è il campo di immissione che il servizio di completamento automatico monitorerà e a cui collegherà i risultati.
  • Un argomento AutocompleteOptions facoltativo, che può contenere le seguenti proprietà:
    • Un array di dati fields da includere nella risposta Place Details per il parametro PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene trasmesso ['ALL'], vengono restituiti e fatturati tutti i campi disponibili (questa operazione non è consigliata per i deployment di produzione). Per un elenco dei campi, vedi PlaceResult.
    • Un array di types che specifica un tipo esplicito o una raccolta di tipi, come elencato tra i tipi supportati. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi.
    • bounds è un oggetto google.maps.LatLngBounds che specifica l'area in cui cercare luoghi. I risultati sono sbilanciati, ma non limitati, ai luoghi contenuti in questi limiti.
    • strictBounds è un boolean che specifica se l'API deve restituire solo i luoghi che si trovano rigorosamente all'interno della regione definita dal bounds specificato. L'API non restituisce risultati al di fuori di questa regione anche se corrispondono all'input dell'utente.
    • Puoi utilizzare componentRestrictions per limitare i risultati a gruppi specifici. Al momento, puoi utilizzare componentRestrictions per filtrare in base a un massimo di cinque paesi. I paesi devono essere trasmessi come codice paese a due caratteri compatibile con ISO 3166-1 Alpha-2. Più paesi devono essere trasmessi come elenco di codici paese.

      Nota: se ricevi risultati imprevisti con un codice paese, verifica di utilizzare un codice che includa i paesi, i territori dipendenti e le aree speciali di interesse geografico che intendi utilizzare. Puoi trovare informazioni sul codice nella pagina Wikipedia: List of ISO 3166 country code (Elenco dei codici paese ISO 3166) o sulla ISO Online Browsing Platform.

    • placeIdOnly può essere utilizzato per indicare al widget Autocomplete di recuperare solo gli ID luogo. Quando chiami getPlace() sull'oggetto Autocomplete, per PlaceResult reso disponibile saranno impostate solo le proprietà place id, types e name. Puoi utilizzare l'ID luogo restituito con chiamate ai servizi Places, Geocoding, Directions o Distance Matrix.

Vincolo delle previsioni di Completamento automatico

Per impostazione predefinita, la funzionalità di completamento automatico di luoghi presenta tutti i tipi di luogo, con influenza sulle previsioni relative alla località in cui si trova l'utente e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta le opzioni di Place Autocomplete per presentare previsioni più pertinenti in base al tuo caso d'uso.

Imposta opzioni in fase di creazione

Il costruttore Autocomplete accetta un parametro AutocompleteOptions per impostare i vincoli al momento della creazione del widget. L'esempio seguente imposta le opzioni bounds, componentRestrictions e types per richiedere i luoghi di tipo establishment, dando la priorità a quelli all'interno dell'area geografica specificata e limitando le previsioni solo ai luoghi degli Stati Uniti. La configurazione dell'opzione fields consente di specificare le informazioni da restituire sul luogo selezionato dall'utente.

Richiama setOptions() per modificare il valore di un'opzione per un widget esistente.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Specifica i campi di dati

Specifica i campi di dati per evitare che ti vengano addebitati SKU di dati Places non necessari. Includi la proprietà fields nel AutocompleteOptions che vengono passati al costruttore del widget, come mostrato nell'esempio precedente, o chiama setFields() su un oggetto Autocomplete esistente.

autocomplete.setFields(["place_id", "geometry", "name"]);

Definisci i bias e i confini dell'area di ricerca per il completamento automatico

Puoi differenziare i risultati del completamento automatico in modo da favorire una posizione o un'area approssimativa, nei seguenti modi:

  • Imposta i limiti alla creazione dell'oggetto Autocomplete.
  • Modifica i limiti su un elemento Autocomplete esistente.
  • Imposta i limiti sull'area visibile della mappa.
  • Limita la ricerca ai limiti.
  • Limitare la ricerca a un paese specifico.

L'esempio precedente mostra i limiti di impostazione al momento della creazione. I seguenti esempi dimostrano le altre tecniche di differenziazione.

Modificare i limiti di un completamento automatico esistente

Richiama setBounds() per modificare l'area di ricerca di un Autocomplete esistente in limiti rettangolari.

TypeScript

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

autocomplete.setBounds(newBounds);

JavaScript

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

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

Utilizza bindTo() per differenziare i risultati nell'area visibile della mappa, anche se quest'ultima cambia.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Utilizza unbind() per svincolare le previsioni di Completamento automatico dall'area visibile della mappa.

TypeScript

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

JavaScript

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

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 });
Limitare le previsioni a un paese specifico

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

TypeScript

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

JavaScript

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

Visualizza esempio

Vincola tipi di luoghi

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

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

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

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

    Oppure:

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

La richiesta verrà rifiutata se:

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

La demo di Places Autocomplete mostra le differenze nelle previsioni tra i diversi tipi di luoghi.

Visita la demo

Recupero delle informazioni sul luogo in corso...

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

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

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

La proprietà name contiene le previsioni description del completamento automatico di Places. Puoi scoprire di più su description nella documentazione di Places Autocomplete.

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

L'esempio seguente utilizza il completamento automatico per compilare i campi in un modulo dell'indirizzo.

TypeScript

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

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

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

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

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

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

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

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

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

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

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

JavaScript

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

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

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

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

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

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

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

window.initAutocomplete = initAutocomplete;

Visualizza esempio

Personalizzazione del testo segnaposto

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

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

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

Per personalizzare l'aspetto del widget, consulta la sezione Stili dei widget Completamento automatico e SearchBox.

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

SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuova", la lista di selezione potrebbe includere la frase "pizza a Roma a Milano" e i nomi di diverse pizzerie. Quando un utente seleziona un luogo dall'elenco, le relative informazioni vengono restituite all'oggetto SearchBox e possono essere recuperate dall'applicazione.

Il costruttore SearchBox accetta due argomenti:

  • Un elemento HTML input di tipo text. Questo è il campo di immissione che il servizio SearchBox monitorerà e a cui collegherà i risultati.
  • Un argomento options, che può contenere la proprietà bounds: bounds è un oggetto google.maps.LatLngBounds che specifica l'area in cui cercare luoghi. I risultati sono differenziati, a titolo esemplificativo, per i luoghi contenuti all'interno di questi limiti.

Il seguente codice utilizza il parametro dei limiti per polarizzare i risultati in base ai luoghi all'interno di una determinata area geografica, specificati tramite coordinate di laitudine/longitudine.

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

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

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

Modifica dell'area di ricerca per SearchBox

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

Visualizza esempio

Recupero delle informazioni sul luogo in corso...

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

Per saperne di più sull'oggetto PlaceResult, consulta la documentazione sui risultati dei dettagli dei luoghi.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      }),
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Visualizza esempio

Per personalizzare l'aspetto del widget, consulta la sezione Stili dei widget Completamento automatico e SearchBox.

Recupero programmatico del servizio Place Autocomplete

Per recuperare le previsioni in modo programmatico, utilizza la classe AutocompleteService. AutocompleteService non aggiunge alcun controllo dell'interfaccia utente. Restituisce invece un array di oggetti di previsione, ciascuno contenente il testo della previsione, le informazioni di riferimento e i dettagli di come il risultato corrisponde all'input dell'utente. Ciò è utile se vuoi un maggiore controllo sull'interfaccia utente rispetto a quello offerto da Autocomplete e SearchBox descritto sopra.

AutocompleteService espone i seguenti metodi:

  • getPlacePredictions() restituisce le previsioni sui luoghi. Nota: un "luogo" può essere un'attività, una posizione geografica o un punto d'interesse di rilievo, come definito dall'API Places.
  • getQueryPredictions() restituisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza nuova", la lista di selezione potrebbe includere la frase "pizza a Roma a Milano" e i nomi di varie pizzerie.

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

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

L'esempio seguente esegue una richiesta di previsione della query per la frase "pizza nelle vicinanze" e mostra il risultato in un elenco.

TypeScript

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

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

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

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

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

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

JavaScript

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

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

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

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

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

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <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.
      See https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Prova Sample

Visualizza esempio

Token di sessione

AutocompleteService.getPlacePredictions() può utilizzare i token di sessione (se implementati) per raggruppare le richieste di completamento automatico ai fini della fatturazione. I token di sessione raggruppano le fasi di query e selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e si conclude quando seleziona un luogo. Ogni sessione può includere più query, seguite da una selezione di un luogo. Al termine di una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Consigliamo di usare i token di sessione per tutte le sessioni di completamento automatico. Se il parametro sessionToken viene omesso o se riutilizzi un token di sessione, la sessione viene addebitata come se non fosse stato fornito un token di sessione (ogni richiesta viene fatturata separatamente).

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

Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più sessioni Autocomplete renderà non valide quelle sessioni Autocomplete, mentre tutte le richieste di Autocomplete nelle sessioni non valide verranno addebitate singolarmente utilizzando lo SKU Autocomplete Per richiesta SKU. Scopri di più sui token di sessione.

L'esempio seguente mostra la creazione di un token di sessione e poi il passaggio in un AutocompleteService (la funzione displaySuggestions() è stata omessa per brevità):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Assicurati di passare un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più sessioni comporterà la fatturazione individuale di ogni richiesta.

Scopri di più sui token di sessione.

Stili dei widget Autocomplete e SearchBox

Per impostazione predefinita, agli elementi dell'interfaccia utente forniti da Autocomplete e SearchBox viene applicato uno stile per l'inclusione su una mappa di Google. Ti consigliamo di modificare lo stile per adattarlo al tuo sito. Sono disponibili le seguenti classi CSS. Tutti i corsi elencati di seguito si applicano sia ai widget Autocomplete che a quelli SearchBox.

Un&#39;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 Place Autocomplete. Questo elenco viene visualizzato come elenco a discesa sotto il widget Autocomplete o SearchBox.
pac-icon L'icona visualizzata a sinistra di ogni elemento nell'elenco delle previsioni.
pac-item Un elemento nell'elenco di previsioni fornito dal widget Autocomplete o SearchBox.
pac-item:hover L'elemento quando l'utente passa sopra il puntatore del mouse.
pac-item-selected L'elemento quando l'utente lo seleziona tramite la tastiera. Nota: gli elementi selezionati faranno parte di questo corso e di pac-item.
pac-item-query Un intervallo all'interno di pac-item che è la parte principale della previsione. Per le località geografiche, contiene il nome di un luogo, come "Sydney", o il nome di una via e un numero civico, ad esempio "Via Roma 10". Per ricerche basate su testo, ad esempio "pizza a New York", questo parametro contiene il testo completo della query. Per impostazione predefinita, il campo pac-item-query è di colore nero. Se è presente testo aggiuntivo in pac-item, si trova all'esterno di pac-item-query e ne eredita lo stile da pac-item. Per impostazione predefinita è di colore grigio. Il testo aggiuntivo è in genere un indirizzo.
pac-matched La parte della previsione restituita che corrisponde all'input dell'utente. Per impostazione predefinita, il testo corrispondente viene evidenziato in grassetto. Tieni presente che il testo corrispondente può trovarsi ovunque all'interno di pac-item. Non fa necessariamente parte di pac-item-query e potrebbe essere in parte all'interno di pac-item-query e in parte nel testo rimanente in pac-item.

Utilizzo del componente Selettore di luogo

Nota:questo esempio utilizza una libreria open source. Consulta la pagina README per ricevere assistenza e feedback relativi alla libreria.

Prova i componenti web. Utilizza il componente web Selettore di luoghi per abilitare l'inserimento di testo che consenta agli utenti finali di cercare un indirizzo o un luogo specifico utilizzando il completamento automatico.

GIF con casella di ricerca. L&#39;utente inizia a digitare un indirizzo come input e viene visualizzato un menu a discesa con gli indirizzi correlati. L&#39;utente fa clic su un indirizzo dal menu a discesa e la casella di ricerca riempie il resto dell&#39;indirizzo.
Figura 1: immissione di testo per cercare un indirizzo o un luogo specifico utilizzando il completamento automatico

Posiziona ottimizzazione del completamento automatico

In questa sezione vengono descritte le best practice per aiutarti a ottenere il massimo dal servizio Place Autocomplete.

Ecco alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget Autocomplete dell'API Maps JavaScript, il widget Autocomplete dell'SDK Places per Android o il controllo dell'interfaccia utente di Autocomplete dell'SDK Places per iOS
  • Sviluppa sin dall'inizio una comprensione dei campi di dati essenziali di Place Autocomplete.
  • I campi per la differenziazione per località e per le limitazioni in base alla località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che la tua app venga ridotta correttamente se l'API restituisce un errore.
  • Assicurati che la tua app sia in grado di gestire quando non è possibile effettuare selezioni e di offrire agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere dei campi nei widget Place Details e Place Autocomplete per restituire solo i campi dei dati del luogo necessari.

Ottimizzazione avanzata dei costi

Prendi in considerazione l'implementazione programmatica di Place Autocomplete per accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding relativi al luogo selezionato anziché a Place Details. I prezzi Per richiesta abbinati all'API Geocoding sono più convenienti rispetto ai prezzi Per sessione (basati su sessione) se vengono soddisfatte entrambe le seguenti condizioni:

  • Se ti servono solo la latitudine/longitudine o l'indirizzo del luogo selezionato dall'utente, l'API Geocoding fornisce queste informazioni per meno di una chiamata Place Details.
  • Se gli utenti selezionano una previsione di completamento automatico in una media di quattro richieste di previsioni di completamento automatico o meno, il prezzo Per richiesta potrebbe essere più conveniente rispetto al prezzo Per sessione.
Per assistenza nella scelta dell'implementazione di Place Autocomplete più adatta alle 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 altri dettagli

Utilizza il completamento automatico basato sulla sessione con Place Details.
Poiché la tua applicazione richiede Place Details come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione di Place Autocomplete deve utilizzare un token di sessione (in modo programmatico o integrato nei widget JavaScript, Android o iOS) per un costo totale di 0,017 $per sessione oltre agli SKU di dati di Places applicabili in base ai campi dei dati dei luoghi richiesti.

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget
JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete che la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi dei dati del luogo necessari.

Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi Place Details (Dettagli locale) per la previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo nella risposta Place Autocomplete
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  3. Il parametro fields che specifica i campi di dati del luogo necessari

No, richiede solo indirizzo e posizione

L'API Geocoding potrebbe essere un'opzione più economica rispetto a Place Details per la tua applicazione, a seconda delle prestazioni dell'utilizzo di Place Autocomplete. L'efficienza di completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, dove viene utilizzata l'applicazione e che sono state implementate best practice per l'ottimizzazione delle prestazioni.

Per rispondere alla seguente domanda, analizza il numero di caratteri digitati in media da un utente prima di selezionare una previsione di Place Autocomplete nella tua applicazione.

I tuoi utenti selezionano una previsione di Place Autocomplete in una media di quattro o meno richieste?

Implementa Place Autocomplete in modo programmatico senza token di sessione e chiama l'API Geocoding nella previsione del luogo selezionata.
L'API Geocoding fornisce indirizzi e coordinate di latitudine/longitudine al costo di 0,005 $per richiesta. Effettuare quattro richieste Place Autocomplete - Per Request costa $0,01132; il costo totale di quattro richieste più una chiamata API Geocoding per la previsione del luogo selezionata sarebbe di $0,01632, che è inferiore al prezzo del completamento automatico per sessione di $0,017 per sessione.1

Valuta la possibilità di adottare le best practice per il rendimento per consentire agli utenti di ottenere le previsioni che cercano utilizzando ancora meno caratteri.

No

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

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Sono incluse sia le richieste Place Autocomplete che la richiesta Place Details per la previsione selezionata. Assicurati di specificare il parametro fields per avere la certezza di richiedere solo i campi Dati di base.

Implementazione programmatica
Utilizza un token di sessione con le richieste Place Autocomplete. Quando richiedi Place Details (Dettagli locale) per la previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo nella risposta Place Autocomplete
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  3. Il parametro fields che specifica i campi Dati di base come l'indirizzo e la geometria

Valuta l'idea di posticipare le richieste di Place Autocomplete
Puoi adottare strategie come il ritardo di una richiesta di Place Autocomplete finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui meno richieste. Ad esempio, fare richieste Place Autocomplete per ogni carattere dopo che l'utente ha digitato il terzo carattere significa che se l'utente digita sette caratteri seleziona quindi una previsione per la quale effettui una richiesta all'API Geocoding, il costo totale sarà di $0,01632 (4 * $0,00283 Autocomplete Per Request + $0,005 Geocoding).1

Se con il ritardo le richieste di pubblicità programmatica sono inferiori alle quattro, puoi seguire le indicazioni per l'implementazione performante Place Autocomplete with Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di ottenere previsioni a ogni nuova pressione di un tasto.

Valuta la possibilità di applicare le best practice per il rendimento per consentire agli utenti di ottenere le previsioni che cercano con meno caratteri.


  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 come ottimizzare le prestazioni del completamento automatico di Place Auto:

  • Aggiungi limitazioni in base al paese, differenziazione per località e (per le implementazioni di pubblicità programmatica) la preferenza della lingua all'implementazione di Place Autocomplete. La preferenza della lingua non è necessaria con i widget perché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico di Place Autocomplete è accompagnato da una mappa, puoi differenziare la posizione in base all'area visibile della mappa.
  • Nei casi in cui un utente non sceglie una delle previsioni di Completamento automatico, in genere perché nessuna di queste previsioni rappresenta l'indirizzo dei risultati desiderato, puoi riutilizzare l'input utente originale per cercare di ottenere risultati più pertinenti:
    • Se prevedi che l'utente inserisca solo informazioni sull'indirizzo, riutilizza l'input utente originale in una chiamata all'API Geocoding.
    • Se prevedi che l'utente inserisca query per un luogo specifico per nome o indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in una regione specifica, utilizza la differenziazione per località.
    Altri scenari in cui è meglio ricorrere all'API Geocoding includono:
    • Utenti che inseriscono indirizzi secondari in paesi in cui il supporto di Place Autocomplete per gli indirizzi secondari è incompleto, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" restituisce una previsione parziale in Place Autocomplete.
    • Gli utenti che inseriscono indirizzi con prefissi dei segmenti di strada come "23-30 29th St, Queens" a New York o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.

Limiti e norme di utilizzo

Quote

Per informazioni su quote e prezzi, consulta la documentazione relativa all'utilizzo e alla fatturazione per l'API Places.

Norme

L'utilizzo della libreria Places, l'API Maps JavaScript deve essere conforme alle norme descritte per l'API Places.