Place Autocomplete

Seleziona piattaforma: Android iOS JavaScript Servizio web

Introduzione

Autocomplete è una funzionalità della libreria Places nell'API Maps JavaScript. Puoi utilizzare il completamento automatico per fornire alle tue applicazioni il comportamento di ricerca in anteprima del campo di ricerca di Google Maps. Il servizio di completamento automatico può stabilire una corrispondenza con parole intere e sottostringhe, 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 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, quindi scegli lo stesso progetto che hai configurato per l'API Maps JavaScript e fai clic su Apri.
  3. Cerca API Places dall'elenco delle API nella Dashboard.
  4. Se vedi l'API nell'elenco, significa che è tutto a posto. 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 e selezionala dall'elenco dei risultati.
    3. Seleziona ABILITA. Al termine del processo, viene visualizzata l'API Places nell'elenco delle API nella 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 innanzitutto 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 con completamento automatico, che potete aggiungere rispettivamente tramite le classi Autocomplete e SearchBox. Inoltre, puoi utilizzare la classe AutocompleteService per recuperare i risultati di completamento automatico a livello di programmazione (consulta il riferimento API Maps JavaScript: Classe AutocompleteService).

Ecco un riepilogo dei corsi disponibili:

  • Autocomplete aggiunge un campo di immissione di testo alla tua pagina web e monitora tale campo per inserire caratteri. Man mano che l'utente inserisce il 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. Vedi i dettagli di seguito.
    Un campo di testo con completamento automatico e l&#39;elenco di selezione delle previsioni
    dei luoghi forniti quando l&#39;utente inserisce la query di ricerca.
    Figura 1: completamento automatico del campo di testo e dell'elenco di selezione
    Un modulo compilato per l&#39;indirizzo.
    Figura 2: modulo dell'indirizzo completato
  • SearchBox aggiunge un campo di immissione di testo alla tua pagina web, nello stesso modo di Autocomplete. Le differenze sono le seguenti:
    • La differenza principale risiede nei risultati visualizzati nell'elenco di selezione. SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) più termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuova", l'elenco di scelta può includere la frase "pizza a New York, NY" e i nomi di vari punti vendita.
    • SearchBox offre meno opzioni rispetto a Autocomplete per limitare la ricerca. Nel primo caso, puoi biasare la ricerca a una determinata LatLngBounds. Nell'ultima versione, 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 compilato per l&#39;indirizzo.
    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 il numero getPlacePredictions() per recuperare i luoghi corrispondenti o chiama il numero getQueryPredictions() per recuperare i luoghi corrispondenti più i termini di ricerca suggeriti. Nota: AutocompleteService non aggiunge controlli UI. I metodi precedenti restituiscono invece una matrice di oggetti di previsione. Ogni oggetto di previsione contiene il testo della previsione, oltre a informazioni di riferimento e dettagli sul modo in cui il risultato corrisponde all'input utente. Consulta i dettagli di seguito.

Aggiungere un widget di completamento automatico

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

Il costruttore Autocomplete accetta due argomenti:

  • Elemento HTML input di tipo text. Si tratta del campo di immissione che il servizio di completamento automatico monitora e allega ai risultati.
  • Un argomento AutocompleteOptions facoltativo, che può contenere le seguenti proprietà:
    • Un array di dati fields da includere nella risposta Place Details per l'elemento PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene trasmesso ['ALL'], tutti i campi disponibili vengono restituiti e fatturati (non consigliato per i deployment di produzione). Per un elenco dei campi, consulta 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 verso, ma non solo, i luoghi all'interno di questi confini.
    • 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.
    • 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 indicati come codice paese compatibile con lo standard 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 vuoi. Puoi trovare informazioni sul codice in Wikipedia: elenco dei codici paese ISO 3166 o nella piattaforma di navigazione online ISO.

    • placeIdOnly può essere usato per indicare al widget Autocomplete di recuperare solo gli ID luogo. Per la chiamata a getPlace() nell'oggetto Autocomplete, per PlaceResult sono disponibili solo le proprietà place id, types e name. Puoi utilizzare l'ID luogo restituito con le chiamate ai servizi Places, Geocoding, Directions o Distance Matrix.

Limitazioni del completamento automatico vincolanti

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

Imposta le opzioni per i lavori in corso

Il costruttore Autocomplete accetta un parametro AutocompleteOptions per impostare i vincoli al momento della creazione del widget. L'esempio che segue imposta 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 dell'opzione fields specifica quali informazioni restituire per il luogo selezionato dell'utente.

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

TypeScript

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

Specifica i campi di dati

Specifica i campi di dati per evitare che ti vengano addebitati SKU di dati di Places non necessari. Includi la proprietà fields in AutocompleteOptions che viene passata 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 di completamento automatico per favorire una posizione o un'area approssimativa, nei seguenti modi:

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

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

Modificare i limiti di un completamento automatico esistente

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

TypeScript

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

autocomplete.setBounds(newBounds);

JavaScript

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

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

Usa bindTo() per bias e mostrare i risultati all'area visibile della mappa, anche se questa 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 correnti

Imposta l'opzione strictBounds per limitare i risultati ai limiti attuali, 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 insieme 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

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 indicato in Tipi di luogo. Se non viene specificato alcun vincolo, vengono restituiti tutti i tipi.

Per il valore dell'opzione types o del valore trasmesso a setTypes(), puoi specificare una delle seguenti opzioni:

  • Un array contenente fino a cinque valori inclusi nella tabella 1 o con la tabella 2 dalla sezione Tipi di luogo. Ad esempio:

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

    Oppure:

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

La richiesta verrà rifiutata se:

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

La demo del completamento automatico di Places mostra le differenze nelle previsioni tra tipi di luoghi diversi.

Visita la demo

Recupero delle informazioni sui luoghi

Quando un utente seleziona un luogo dalle previsioni collegate al campo di testo con completamento automatico, il servizio attiva un evento place_changed. Per ottenere 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() 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 ti verrà addebitato il costo corrispondente. Utilizza Autocomplete.setFields() per specificare i campi di dati dei luoghi da restituire. Scopri di più sull'oggetto PlaceResult, incluso 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 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 degli indirizzi, è utile avere 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 di 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 dei segnaposto

Per impostazione predefinita, il campo di testo creato dal servizio di completamento automatico contiene il 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 predefinito del segnaposto 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 il linguaggio da utilizzare, leggi la documentazione sulla localizzazione.

Per personalizzare l'aspetto del widget, consulta l'articolo Applicazione dei widget di completamento automatico e casella di ricerca.

SearchBox consente agli utenti di eseguire ricerche geografiche basate su testo, ad esempio "pizza a New York" o "negozi di scarpe vicino a Robson Street". Puoi collegare SearchBox a un campo di testo e, man mano che inserisci il testo, il servizio restituirà le previsioni sotto forma di un elenco a discesa.

SearchBox fornisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) più termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuova", l'elenco di scelta potrebbe includere la frase "pizza a New York, NY" e i nomi di vari punti vendita. Quando un utente seleziona un luogo dall'elenco, le informazioni su tale luogo vengono restituite all'oggetto SearchBox e possono essere recuperate dall'applicazione.

Il costruttore SearchBox accetta due argomenti:

  • Elemento HTML input di tipo text. Questo è il campo di immissione che verrà monitorato dal servizio SearchBox e ne collega 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 verso, ma non limitati a, i luoghi contenuti in questi limiti.

Il codice riportato di seguito utilizza il parametro bounds per indirizzare i risultati verso luoghi all'interno di una particolare area geografica, specificate 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 della casella di ricerca

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

Visualizza esempio

Recupero delle informazioni sui luoghi

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, ciascuna delle quali è un oggetto PlaceResult.

Per maggiori informazioni sull'oggetto PlaceResult, consulta la documentazione sui risultati dettagliati 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 l'articolo Applicazione dei widget di completamento automatico e casella di ricerca.

Recupero programmatico del servizio Place Autocomplete previsioni

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

AutocompleteService espone i seguenti metodi:

  • getPlacePredictions() restituisce le previsioni dei luoghi. Nota: un "luogo" può essere una struttura, una posizione geografica o un punto d'interesse di spicco, come definito dall'API Places.
  • getQueryPredictions() restituisce un elenco esteso di previsioni, che possono includere luoghi (come definiti dall'API Places) oltre ai termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "pizza in nuova", l'elenco di scelta potrebbe includere la frase "pizza a New York, NY" e i nomi di vari punti vendita.

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 dal AutocompletionRequest.origin specificato.
  • matched_substrings contiene una serie di sottostringhe nella descrizione che corrispondono a elementi inseriti dall'utente. Questo è utile per evidenziare queste sottostringhe nella tua applicazione. In molti casi, la query viene visualizzata come sottostringa del campo della descrizione.
    • length è la lunghezza della sottostringa.
    • offset è l'offset del carattere, misurato dall'inizio della stringa descrittiva in cui compare 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. Per un luogo, ogni elemento solitamente costituisce una parte dell'indirizzo.
    • offset è l'offset del carattere, misurato dall'inizio della stringa descrittiva in cui compare la sottostringa corrispondente.
    • value è il termine corrispondente.

L'esempio riportato di seguito esegue una richiesta di previsione per la frase "pizza vicino" e visualizza il risultato in un elenco.

TypeScript

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

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

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

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

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

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

JavaScript

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

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

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

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

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

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete Predictions</title>
    <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 anteprima

Visualizza 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 con completamento automatico dell'utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare una query e termina 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 alla sessione avviene come se non fosse stato fornito alcun token (ogni richiesta viene fatturata separatamente).

Puoi utilizzare lo stesso token di sessione per effettuare una singola richiesta Dettagli luogo sul luogo risultante da una chiamata al numero 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ù di una sessione di completamento automatico invaliderà tali sessioni e 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 come creare un token di sessione, quindi lo trasmette 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 di ogni richiesta.

Scopri di più sui token di sessione.

Stile dei widget Autocomplete e SearchBox

Per impostazione predefinita, gli elementi UI forniti da Autocomplete e SearchBox sono adatti all'inclusione 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.

Un&#39;illustrazione grafica delle classi CSS per i widget Autocomplete e SearchBox
Classi CSS per i widget Autocomplete e SearchBox
lezione CSS Descrizione
pac-container L'elemento visivo contenente l'elenco delle previsioni restituite dal servizio di completamento automatico dei luoghi. 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 su cui passa il puntatore del mouse.
pac-item-selected L'elemento quando l'utente lo seleziona tramite la tastiera. Nota: gli elementi selezionati saranno membri di questa classe e della classe pac-item.
pac-item-query Un intervallo all'interno di un elemento pac-item che costituisce la parte principale della previsione. Per le posizioni geografiche, questo contiene il nome di un luogo, ad esempio "Sydney" oppure il nome e il numero della via, ad esempio "10 King Street". Per le ricerche testuali, ad esempio "pizza a New York", contiene il testo completo della query. Per impostazione predefinita, il colore pac-item-query è nero. Se il testo è pac-item, è esterno 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 della corrispondenza è evidenziato in grassetto. Tieni presente che il testo corrispondente potrebbe essere 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 nonché in parte nel testo rimanente in pac-item.

Effettua l'ottimizzazione di completamento automatico

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

Ecco alcune linee guida generali:

  • Il modo più rapido per sviluppare un'interfaccia utente funzionante è utilizzare il widget di completamento automatico dell'API Maps JavaScript, il widget di completamento automatico di Places per Android o il controllo interfaccia utente di completamento automatico di Places per iOS
  • Sviluppa una comprensione iniziale dei campi di dati di completamento automatico del luogo.
  • I campi di differenziazione della posizione e di limitazione della località 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 sia gestita quando non è presente alcuna selezione e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

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

Ottimizzazione avanzata dei costi

Valuta la possibilità di implementare il completamento automatico dei luoghi per poter accedere ai prezzi per richiesta e richiedere i risultati dell'API Geocoding anziché i dettagli del luogo selezionato. I prezzi per richiesta abbinati all'API Geocoding sono più efficaci rispetto ai prezzi per sessione (basati su sessione) se vengono soddisfatte entrambe le seguenti condizioni:

  • Se ti serve soltanto la latitudine/longitudine o l'indirizzo del luogo selezionato dell'utente, l'API Geocoding fornisce queste informazioni a meno di una chiamata Dettagli luogo.
  • Se gli utenti selezionano una previsione di completamento automatico entro una media di quattro richieste 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 in base alle tue esigenze, seleziona la scheda che corrisponde 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 relativi al luogo, come il nome del luogo, lo stato dell'attività o l'orario di apertura, l'implementazione del completamento automatico del luogo 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 più SKU di dati dei luoghi a seconda dei campi di dati dei luoghi che richiedi.1

Implementazione dei widget
La gestione delle sessioni è integrata automaticamente nei widget JavaScript, Android o iOS. Ciò include sia le richieste di completamento automatico del luogo sia la richiesta Dettagli luogo nella previsione selezionata. Assicurati di specificare il parametro fields per assicurarti di richiedere solo i campi di dati sui luoghi necessari.

Implementazione programmatica
Utilizza un token di sessione con le richieste di completamento automatico dei lavori in corso. Quando richiedi i dettagli del luogo relativi alla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo dalla risposta di 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, richiede solo 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 del completamento automatico di Place. L'efficienza del completamento automatico di ogni applicazione varia a seconda dei dati per cui gli utenti accedono al programma, della località in cui viene utilizzata e se sono state implementate best practice per l'ottimizzazione delle prestazioni.

Per rispondere alla seguente domanda, analizza la quantità di caratteri digitata da un utente prima di selezionare una previsione di completamento automatico del posizionamento nella tua applicazione.

In media, gli utenti selezionano una previsione di completamento automatico del luogo in quattro richieste o meno?

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

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

No

Utilizza il completamento automatico dei luoghi basato sulla sessione con i dettagli del luogo.
Poiché il numero medio di richieste che dovresti effettuare prima che un utente selezioni una previsione di completamento automatico del luogo che supera il costo dei prezzi per sessione, la tua implementazione del completamento automatico del luogo dovrebbe utilizzare un token di sessione sia per le richieste di completamento automatico del luogo sia per la richiesta Dettagli luogo 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. Ciò include sia le richieste di completamento automatico del luogo sia la richiesta Dettagli luogo 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 lavori in corso. Quando richiedi i dettagli del luogo relativi alla previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo dalla risposta di 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, ad esempio indirizzo e geometria

Ritardo delle richieste di completamento automatico dei luoghi
Puoi utilizzare strategie per ritardare una richiesta di completamento automatico dei luoghi finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione effettui un numero inferiore di richieste. Ad esempio, effettuando richieste di completamento automatico del posizionamento per ogni carattere dopo che l'utente ha digitato il terzo carattere, significa che se l'utente digita sette caratteri e poi seleziona una previsione per la quale si effettua una richiesta API Geocoding, il costo totale sarà pari a $0,01632 (4 * $0,00283 completamento automatico per richiesta + $0,005 geocodifica).1

Se le richieste in ritardo possono raggiungere un numero medio di richieste di pubblicità programmatica inferiore a quattro, puoi seguire le indicazioni per l'implementazione del completamento automatico dei luoghi con API Geocoding. Tieni presente che le richieste ritardate possono essere percepite come latenza dall'utente, che può aspettarsi di vedere le previsioni a ogni nuova sequenza di tasti.

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


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

Best practice per il rendimento

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

  • Aggiungi limitazioni in base al paese, targeting per località e (per implementazioni programmatiche) le preferenze di lingua per l'implementazione di Place Autocomplete. La preferenza della lingua non è necessaria con i widget perché scelgono le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico del luogo è accompagnato da una mappa, puoi bias la posizione in base all'area visibile della mappa.
  • Nelle situazioni in cui un utente non sceglie una delle previsioni del completamento automatico, in genere perché nessuna di queste previsioni è l'indirizzo dei risultati desiderato, puoi riutilizzare l'input originale dell'utente per tentare di ottenere risultati più pertinenti:
    • Se prevedi che l'utente debba inserire solo informazioni relative all'indirizzo, puoi riutilizzare l'input utente originale durante una chiamata all'API Geocoding.
    • Se prevedi che l'utente inserisce query per un luogo specifico in base al nome o all'indirizzo, utilizza una richiesta Trova luogo. Se i risultati sono previsti solo in una regione specifica, utilizza la ponderazione della posizione.
    Altri scenari in cui è meglio utilizzare l'API Geocoding sono:
    • Gli utenti che inseriscono indirizzi di sottopreside in paesi in cui il supporto del completamento automatico degli indirizzi di pre-completamento è incompleto, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praga" genera una previsione parziale nel completamento automatico del luogo.
    • Utenti che inseriscono indirizzi con prefissi del tratto di strada come "23-30 29th St, Queens" a New York City o "47-380 Kamehameha Hwy, Kaneohe" sull'isola di Kauai alle Hawaii.

Limiti e criteri di utilizzo

Quote

Per informazioni sulle quote e sui prezzi, consulta la documentazione relativa a utilizzo e fatturazione per l'API Places.

Criteri

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