Place Autocomplete

Seleziona la piattaforma: Android iOS JavaScript Servizio web

Introduzione

Il completamento automatico è una funzionalità della libreria Places nell'API Maps JavaScript. Puoi utilizzare il completamento automatico per fornire alle tue applicazioni il comportamento di ricerca con completamento 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 tipi di utente per fornire previsioni immediate.

Come iniziare

Prima di utilizzare la libreria Places nell'API Maps JavaScript, assicurati che l'API Places sia attivata 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, quindi 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, significa che è tutto a posto. 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 sulla 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 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 possono essere aggiunti rispettivamente tramite le classi Autocomplete e SearchBox. Inoltre, puoi utilizzare la classe AutocompleteService per recuperare i risultati del completamento automatico in modo programmatico (consulta la documentazione di riferimento per l'API Maps JavaScript: classe AutocompleteService).

Di seguito è riportato un riepilogo dei corsi disponibili:

  • Autocomplete aggiunge un campo di immissione testo alla tua pagina web e monitora tale campo per rilevare eventuali caratteri. Mentre l'utente inserisce il testo, il completamento automatico restituisce le previsioni delle posizioni sotto forma di elenco a discesa. Quando l'utente seleziona un luogo dall'elenco, le relative informazioni vengono restituite all'oggetto di completamento automatico che possono essere recuperate dall'applicazione. Vedi i dettagli di seguito.
    Un campo di testo con completamento automatico e l&#39;elenco di selezione delle previsioni dei luoghi fornite quando l&#39;utente inserisce la query di ricerca.
    Figura 1: campo di testo con completamento automatico e elenco di selezione
    Un modulo per l&#39;indirizzo compilato.
    Figura 2: modulo dell'indirizzo completo
  • SearchBox aggiunge un campo di immissione testo alla tua pagina web, in modo molto simile a 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 può includere luoghi (come definiti dall'API Places) e termini di ricerca suggeriti. Ad esempio, se l'utente inserisce "nuova pizza", l'elenco potrebbe includere la frase "pizza a New York, NY" 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 che presenta termini di ricerca e previsioni sui luoghi.
    Vedi i dettagli di seguito.
  • Puoi creare un oggetto AutocompleteService per recuperare le previsioni in modo programmatico. Chiama getPlacePredictions() per recuperare i luoghi corrispondenti oppure chiama il numero getQueryPredictions() per recuperare i luoghi corrispondenti e i termini di ricerca suggeriti. Nota: AutocompleteService non aggiunge alcun controllo dell'interfaccia utente. I metodi precedenti, invece, restituiscono un array di oggetti di previsione. Ogni oggetto di previsione contiene il testo della previsione, nonché informazioni di riferimento e dettagli su come il risultato corrisponde all'input dell'utente. Vedi i dettagli di seguito.

Aggiunta di un widget Completamento automatico

Il widget Autocomplete crea un campo di immissione testo nella tua pagina web, fornisce previsioni dei luoghi in un elenco di selezione dell'interfaccia utente e restituisce i dettagli dei luoghi 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:

  • Un elemento HTML input di tipo text. Questo è il campo di immissione che il servizio di completamento automatico monitora e al quale allega i risultati.
  • Un argomento AutocompleteOptions facoltativo, che può contenere le seguenti proprietà:
    • Un array di dati fields da includere nella risposta Place Details per il parametro PlaceResult selezionato dall'utente. Se la proprietà non è impostata o se viene trasmesso ['ALL'], tutti i campi disponibili vengono restituiti e fatturati per (questo non è consigliato per i deployment di produzione). Per un elenco dei campi, vedi PlaceResult.
    • Un array di types che specifica un tipo esplicito o una raccolta di tipi, come elencato nei tipi supportati. Se non viene specificato alcun tipo, vengono restituiti tutti i tipi.
    • bounds è un oggetto google.maps.LatLngBounds che specifica l'area in cui cercare luoghi. I risultati sono polarizzati, ma non limitati a, luoghi contenuti all'interno di 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 utente.
    • componentRestrictions può essere utilizzato 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 lo standard ISO 3166-1 Alpha-2. È necessario specificare più paesi 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: Elenco dei codici paese ISO 3166 o nella piattaforma di navigazione online ISO.

    • 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 vengono impostate solo le proprietà place id, types e name. Puoi utilizzare l'ID luogo restituito con le chiamate ai servizi Luoghi, Geocodifica, Indicazioni stradali o Matrice di distanza.

Vincolare le previsioni di Completamento automatico

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

Imposta opzioni in fase di allestimento

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 luoghi di tipo establishment, privilegiando quelli all'interno dell'area geografica specificata e limitando le previsioni solo per i luoghi all'interno degli Stati Uniti. La configurazione dell'opzione fields consente di specificare quali informazioni 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 costi per gli SKU di dati dei luoghi non necessari. Includi la proprietà fields nella 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 bias e 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 di creazione dell'oggetto Autocomplete.
  • Modifica i limiti di un'entità Autocomplete esistente.
  • Imposta i limiti sulla visualizzazione 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 mostrano 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 in base all'area visibile della mappa, anche quando 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 attuali, in base all'area visibile sulla 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 indicato in Place Tipi. 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 di Tipi di luogo. Ad esempio:

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

    Oppure:

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

La richiesta verrà rifiutata se:

  • Puoi specificare più di cinque tipi.
  • Puoi specificare eventuali tipi non riconosciuti.
  • Puoi mescolare qualsiasi tipo 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 luogo.

Visita la demo

Recupero delle informazioni sul luogo in corso...

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

  1. Crea un gestore di eventi per l'evento place_changed e chiama addListener() sull'oggetto Autocomplete per aggiungere il gestore.
  2. Chiama Autocomplete.getPlace() sull'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 verranno fatturati gli importi corrispondenti. Utilizza Autocomplete.setFields() per specificare quali campi di 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 usare Autocomplete.setFields() per specificare solo i dati dei luoghi che utilizzerai.

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

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 per l'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 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 tale valore nell'applicazione. Per informazioni sulla scelta della lingua da utilizzare da parte dell'API Google Maps JavaScript, 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 viene inserito il testo, il servizio restituirà le previsioni sotto forma di elenco a discesa.

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 "nuova pizza", l'elenco potrebbe includere la frase "pizza a New York, NY" e i nomi di varie 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 sbilanciati, ma non limitati, ai 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 le 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
});

Modifica dell'area di ricerca per la casella di ricerca

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 tra le 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 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.

Recuperare a livello di programmazione le previsioni del servizio di completamento automatico dei luoghi

Per recuperare le previsioni in modo programmatico, utilizza la classe AutocompleteService. AutocompleteService non aggiunge alcun controllo UI. 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 avere un maggiore controllo sull'interfaccia utente rispetto a quello offerto dai criteri Autocomplete e SearchBox descritti sopra.

AutocompleteService espone i seguenti metodi:

  • getPlacePredictions() restituisce le previsioni dei luoghi. Nota: un "luogo" può essere un luogo, un luogo, una posizione geografica o un punto di interesse importante, come definito dall'API Places.
  • getQueryPredictions() restituisce 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 "nuova pizza", l'elenco potrebbe includere la frase "pizza a New York, NY" 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. Ciò è utile per evidenziare queste sottostringhe nell'applicazione. In molti casi, la query verrà visualizzata come sottostringa del campo descrizione.
    • length è la lunghezza della sottostringa.
    • offset è l'offset di caratteri, misurato a partire dall'inizio della stringa descrittiva, in corrispondenza del quale compare 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 contenente gli elementi della query. Per un luogo, ogni elemento in genere costituisce una parte dell'indirizzo.
    • offset è l'offset di caratteri, misurato a partire dall'inizio della stringa descrittiva, in corrispondenza del quale compare la sottostringa corrispondente.
    • value è il termine corrispondente.

L'esempio seguente esegue una richiesta di previsione della query per la frase "pizza nelle vicinanze" 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.
      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 Samples

Visualizza esempio

Token di sessione

AutocompleteService.getPlacePredictions() utilizza i token di sessione per raggruppare le richieste di completamento automatico ai fini della fatturazione. I token di sessione raggruppano le fasi di query e selezione di una ricerca con completamento automatico da 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ò avere più query, seguite da un luogo selezionato. Una volta terminata una sessione, il token non è più valido. L'app deve generare un nuovo token per ogni sessione. Ti consigliamo di usare 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 alcun token di sessione (ogni richiesta viene fatturata separatamente).

Puoi utilizzare lo stesso token di sessione per effettuare una singola richiesta Place Details per il luogo risultante da una chiamata a AutocompleteService.getPlacePredictions(). In questo caso, la richiesta di completamento automatico viene combinata con la richiesta Place Details e la chiamata viene addebitata come una normale richiesta Place Details. 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 di completamento automatico renderà non valide quelle sessioni di completamento automatico e tutte le richieste di completamento automatico nelle sessioni non valide verranno addebitate singolarmente utilizzando lo SKU di completamento automatico per richiesta. Scopri di più sui token di sessione.

L'esempio seguente mostra la creazione di un token di sessione e il relativo trasferimento 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. Se utilizzi lo stesso token per più sessioni, ogni richiesta verrà fatturata singolarmente.

Scopri di più sui token di sessione.

Stili dei widget Completamento automatico e Casella di ricerca

Per impostazione predefinita, gli elementi UI forniti da Autocomplete e SearchBox vengono definiti per l'inclusione in una mappa Google. Ti consigliamo di regolare lo stile per adattarlo al tuo sito. Sono disponibili le seguenti classi CSS. Tutte le classi elencate di seguito si applicano a entrambi i widget Autocomplete e SearchBox.

Illustrazione grafica delle classi CSS per i widget Autocomplete e SearchBox
Classi CSS per i widget Autocomplete e SearchBox
Classe CSS Descrizione
pac-container L'elemento visivo contenente l'elenco di previsioni restituite dal servizio Place Autocomplete. L'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 vi passa sopra con il puntatore del mouse.
pac-item-selected L'elemento quando l'utente lo seleziona tramite tastiera. Nota: gli elementi selezionati faranno parte di questo corso e di pac-item.
pac-item-query Un intervallo all'interno di un elemento pac-item che è la parte principale della previsione. Per le località geografiche, contiene il nome di un luogo, ad esempio "Sydney", o il nome e il numero di una via, ad esempio "Via Roma 10". Per ricerche basate su testo come "pizza a New York", questo contiene il testo completo della query. Per impostazione predefinita, pac-item-query è di colore nero. Se è presente testo aggiuntivo in pac-item, è esterno a pac-item-query e eredita il suo 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.

Posiziona l'ottimizzazione del completamento automatico

Questa sezione descrive le best practice per aiutarti a utilizzare al meglio il servizio Place Autocomplete.

Di seguito sono riportate 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 dell'SDK Places per Android o il controllo dell'interfaccia utente di completamento automatico dell'SDK Places per iOS.
  • Comprendi fin dall'inizio i campi di dati essenziali del completamento automatico di Place.
  • I campi relativi alla differenziazione per località e alla limitazione della località sono facoltativi, ma possono avere un impatto significativo sulle prestazioni del completamento automatico.
  • Utilizza la gestione degli errori per assicurarti che la qualità dell'app venga ridotta correttamente se l'API restituisce un errore.
  • Assicurati che la tua app gestisca quando non è possibile effettuare selezioni e offra agli utenti un modo per continuare.

Best practice per l'ottimizzazione dei costi

Ottimizzazione dei costi di base

Per ottimizzare il costo dell'utilizzo del servizio Place Autocomplete, utilizza le maschere dei campi nei widget 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 a quelli 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 offre queste informazioni meno di una chiamata Place Details.
  • Se gli utenti selezionano una previsione di completamento automatico in una media di quattro richieste di previsione di completamento automatico o meno, i prezzi per richiesta potrebbero essere più convenienti rispetto a quelli per sessione.
Per assistenza nella scelta dell'implementazione di Place Autocomplete adatta alle tue esigenze, seleziona la scheda che corrisponde alla tua risposta alla seguente domanda.

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

Sì, sono necessari altri dettagli

Utilizza il completamento automatico di Place basato sulla sessione con Dettagli luogo.
Poiché la tua applicazione richiede Dettagli luogo 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 relativi al luogo richiesti.

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

Implementazione programmatica
Usa un token di sessione con le tue richieste Place Autocomplete. Quando richiedi Place Details per la previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo nella risposta di completamento automatico di Place
  2. Il token di sessione utilizzato nella richiesta Place Autocomplete
  3. Il parametro fields che specifica i campi dei 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 del tuo utilizzo di Place Autocomplete. L'efficienza di completamento automatico di ogni applicazione varia a seconda di ciò che gli utenti inseriscono, dove l'applicazione viene utilizzata e se sono state implementate best practice per l'ottimizzazione delle prestazioni.

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

I tuoi utenti selezionano una previsione di Completamento automatico dei luoghi in quattro o meno richieste, in media?

Implementa Place Autocomplete in modo programmatico senza token di sessione e chiama l'API Geocoding sulla previsione del luogo selezionato.
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, quindi 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 le prestazioni per aiutare gli utenti a ottenere la previsione che cercano in ancora meno caratteri.

No

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

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

Implementazione programmatica
Usa un token di sessione con le tue richieste Place Autocomplete. Quando richiedi Place Details per la previsione selezionata, includi i seguenti parametri:

  1. L'ID luogo nella risposta di completamento automatico di Place
  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 ritardare le richieste di Place Autocomplete
Puoi utilizzare strategie come ritardare una richiesta di Place Autocomplete finché l'utente non ha digitato i primi tre o quattro caratteri, in modo che l'applicazione invii 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 e seleziona 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 un ritardo le richieste di pubblicità programmatica sono inferiori a quattro, puoi seguire le indicazioni per l'implementazione del completamento automatico di un luogo con l'API Geocoding. Tieni presente che il ritardo delle richieste può essere percepito come latenza dall'utente, che potrebbe aspettarsi di vedere previsioni a ogni nuova pressione di un tasto.

Valuta la possibilità di adottare le best practice per il rendimento per aiutare gli utenti a ottenere la previsione che cercano con meno caratteri.


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

Best practice per il rendimento

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

  • Aggiungi limitazioni in base al paese, differenziazione per località e preferenze linguistiche (per le implementazioni di pubblicità programmatica) all'implementazione di Place Autocomplete. La preferenza della lingua non è necessaria con i widget, poiché selezionano le preferenze relative alla lingua dal browser o dal dispositivo mobile dell'utente.
  • Se il completamento automatico di Place è accompagnato da una mappa, puoi differenziare la posizione in base all'area visibile sulla mappa.
  • Nelle situazioni in cui un utente non sceglie una delle previsioni di completamento automatico, in genere perché nessuna di queste previsioni è l'indirizzo risultato 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 in base al nome o all'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 del completamento automatico di Place Auto per gli indirizzi delle sedi secondarie è incompleto, ad esempio Cechia, Estonia e Lituania. Ad esempio, l'indirizzo ceco "Stroupežnického 3191/17, Praha" fornisce una previsione parziale in Place Autocomplete.
    • Gli utenti inseriscono gli indirizzi con prefissi di segmenti 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 norme di utilizzo

Quote

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

Criteri

L'utilizzo dell'API Places Library, l'API Maps JavaScript deve essere conforme ai criteri descritti per l'API Places.