API Place Autocomplete Data

L'API Place Autocomplete Data ti consente di recuperare le previsioni dei luoghi in modo programmatico, per creare esperienze di completamento automatico personalizzate con un controllo più preciso di quanto non sia possibile fare con il widget di completamento automatico. In questa guida, imparerai a utilizzare Posiziona l'API Autocomplete Data per effettuare richieste di completamento automatico in base all'utente query.

L'esempio seguente mostra un'integrazione semplice type-ahead. Inserisci la query di ricerca, poi fai clic su per selezionare il risultato desiderato.

Richieste Autocomplete

Una richiesta di completamento automatico prende una stringa di input della query e restituisce un elenco di previsioni dei luoghi. A effettua una richiesta di completamento automatico, chiama fetchAutocompleteSuggestions() e passare una richiesta con le proprietà necessarie. La input contiene la stringa da cercare; in un'applicazione tipica questo valore viene aggiornato l'utente digita una query. La richiesta deve includere un elemento sessionToken, utilizzato ai fini della fatturazione.

Lo snippet seguente mostra la creazione di un corpo della richiesta e l'aggiunta di un token di sessione, quindi la chiamata fetchAutocompleteSuggestions() per visualizzare un elenco di PlacePrediction. 

// Add an initial request body.
let request = {
  input: "Tadi",
  locationRestriction: {
    west: -122.44,
    north: 37.8,
    east: -122.39,
    south: 37.78,
  },
  origin: { lat: 37.7893, lng: -122.4039 },
  includedPrimaryTypes: ["restaurant"],
  language: "en-US",
  region: "us",
};
// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;

index.js

Limita previsioni di completamento automatico

Per impostazione predefinita, Place Autocomplete presenta tutti i tipi di luogo, con una differenziazione delle previsioni in base alle posizione e recupera tutti i campi di dati disponibili per il luogo selezionato dell'utente. Imposta luogo Opzioni di completamento automatico per presentare previsioni più pertinenti, limitando o differenziando i risultati.

Se limiti i risultati, il widget di completamento automatico ignora tutti i risultati al di fuori del area ad accesso limitato. È prassi comune limitare i risultati ai limiti della mappa. Differenziazione dei risultati mostra al widget di completamento automatico i risultati all'interno dell'area specificata, ma alcune corrispondenze potrebbero essere al di fuori di quell'area.

Utilizza la proprietà origin per specificare il punto di origine da cui calcolare distanza geodetica dalla destinazione. Se questo valore viene omesso, la distanza non viene restituita.

Utilizza la includedPrimaryTypes per specificare fino a cinque tipi di luogo. Se non viene specificato alcun tipo, verranno restituiti luoghi di tutti i tipi.

Consulta la documentazione di riferimento dell'API

Visualizza i dettagli del luogo

Per restituire un Place oggetto da un risultato della previsione di un luogo, prima chiamata toPlace(), quindi chiama fetchFields() sull'oggetto Place risultante (l'ID sessione della previsione del luogo viene incluso automaticamente). La chiamata a fetchFields() termina il sessione di completamento automatico. 

let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.

await place.fetchFields({
  fields: ["displayName", "formattedAddress"],
});

const placeInfo = document.getElementById("prediction");

placeInfo.textContent =
  "First predicted place: " +
  place.displayName +
  ": " +
  place.formattedAddress;
index.js

Token di sessione

I token di sessione raggruppano le fasi di query e selezione della ricerca con completamento automatico di un utente in un sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare. La sessione termina quando l'utente seleziona un luogo e viene effettuata una chiamata a Place Details.

Per creare un nuovo token di sessione e aggiungerlo a una richiesta, crea un'istanza di AutocompleteSessionToken, imposta sessionToken della richiesta di utilizzare i token, come mostrato nello snippet seguente: 

// Create a session token.
const token = new AutocompleteSessionToken();

// Add the token to the request.
// @ts-ignore
request.sessionToken = token;

index.js

Una sessione viene terminata quando fetchFields() . Dopo aver creato l'istanza Place, non è necessario superare la sessione in fetchFields() poiché viene gestito automaticamente. 

await place.fetchFields({
  fields: ["displayName", "formattedAddress"],
});

index.js
 
await place.fetchFields({
    fields: ['displayName'],
  });

Crea un token di sessione per la prossima sessione creando una nuova istanza di AutocompleteSessionToken.

Suggerimenti per il token di sessione:

  • Utilizza i token di sessione per tutte le chiamate Place Autocomplete.
  • Generare un nuovo token per ogni sessione.
  • Passa un token di sessione univoco per ogni nuova sessione. Utilizzo dello stesso token per più di una sessione farà sì che ogni richiesta venga fatturata individualmente.

Facoltativamente, puoi omettere il token di sessione di completamento automatico da una richiesta. Se il token di sessione è omesso, ogni richiesta viene fatturata separatamente, attivando il Completamento automatico - Per richiesta . Se riutilizzi un token di sessione, la sessione viene considerata non valida e le richieste vengono addebitate come se non fosse stato fornito alcun token di sessione.

Esempio

Mentre l'utente digita una query, viene chiamata una richiesta di completamento automatico le sequenze di tasti (non per carattere) e viene restituito un elenco di possibili risultati. Quando l'utente effettua una selezione dall'elenco dei risultati, la selezione viene conteggiata come una richiesta, in cui tutte le richieste effettuate durante la ricerca vengono raggruppate conteggiati come una singola richiesta. Se l'utente seleziona un luogo, la query di ricerca viene disponibile senza costi aggiuntivi e viene addebitata solo la richiesta di dati del luogo. Se l'utente non effettua una entro pochi minuti dall'inizio della sessione, solo il della query di ricerca viene addebitato.

Dal punto di vista di un'app, il flusso di eventi si svolge in questo modo:

  1. Un utente inizia a digitare una query per cercare "Parigi, Francia".
  2. Dopo aver rilevato l'input dell'utente, l'app crea una nuova sessione "Token A".
  3. Mentre l'utente digita, l'API effettua una richiesta di completamento automatico a intervalli con un nuovo elenco di potenziali risultati per ciascuno:
    "P"
    "Par"
    "Parigi",
    "Parigi, Ven"
  4. Quando l'utente effettua una selezione:
    • Tutte le richieste derivanti dalla query vengono raggruppate e aggiunte al sessione rappresentata da "Token A", come richiesta singola.
    • La selezione dell'utente viene conteggiata come una richiesta Dettagli luogo e viene aggiunta alla sessione rappresentata da "Token A".
  5. La sessione si è conclusa e l'app scarta il "Token A".
di Gemini Advanced. Scopri come vengono fatturate le sessioni

Codice di esempio completo

Questa sezione contiene esempi completi che mostrano come utilizzare l'API Place Autocomplete Data .

Posiziona le previsioni di completamento automatico

L'esempio seguente mostra la chiamata fetchAutocompleteSuggestions() per l'input "Tadi", quindi chiama toPlace() sul primo risultato della previsione, seguito da una chiamata al numero fetchFields() per conoscere i dettagli del luogo.

TypeScript

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
    // @ts-ignore
    const { Place, AutocompleteSessionToken, AutocompleteSuggestion } = await google.maps.importLibrary("places") as google.maps.PlacesLibrary;

    // Add an initial request body.
    let request = {
        input: "Tadi",
        locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 },
        origin: { lat: 37.7893, lng: -122.4039 },
        includedPrimaryTypes: ["restaurant"],
        language: "en-US",
        region: "us",
    };

    // Create a session token.
    const token = new AutocompleteSessionToken();
    // Add the token to the request.
    // @ts-ignore
    request.sessionToken = token;
    // Fetch autocomplete suggestions.
    const { suggestions } = await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    const title = document.getElementById('title') as HTMLElement;
    title.appendChild(document.createTextNode('Query predictions for "' + request.input + '":'));

    for (let suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a new list element.
        const listItem = document.createElement('li');
        const resultsElement = document.getElementById("results") as HTMLElement;
        listItem.appendChild(document.createTextNode(placePrediction.text.toString()));
        resultsElement.appendChild(listItem);
    }

    let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });

    const placeInfo = document.getElementById("prediction") as HTMLElement;
    placeInfo.textContent = 'First predicted place: ' + place.displayName + ': ' + place.formattedAddress;

}

init();
index.ts

JavaScript

/**
 * Demonstrates making a single request for Place predictions, then requests Place Details for the first result.
 */
async function init() {
  // @ts-ignore
  const { Place, AutocompleteSessionToken, AutocompleteSuggestion } =
    await google.maps.importLibrary("places");
  // Add an initial request body.
  let request = {
    input: "Tadi",
    locationRestriction: {
      west: -122.44,
      north: 37.8,
      east: -122.39,
      south: 37.78,
    },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ["restaurant"],
    language: "en-US",
    region: "us",
  };
  // Create a session token.
  const token = new AutocompleteSessionToken();

  // Add the token to the request.
  // @ts-ignore
  request.sessionToken = token;

  // Fetch autocomplete suggestions.
  const { suggestions } =
    await AutocompleteSuggestion.fetchAutocompleteSuggestions(request);
  const title = document.getElementById("title");

  title.appendChild(
    document.createTextNode('Query predictions for "' + request.input + '":'),
  );

  for (let suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a new list element.
    const listItem = document.createElement("li");
    const resultsElement = document.getElementById("results");

    listItem.appendChild(
      document.createTextNode(placePrediction.text.toString()),
    );
    resultsElement.appendChild(listItem);
  }

  let place = suggestions[0].placePrediction.toPlace(); // Get first predicted place.

  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  const placeInfo = document.getElementById("prediction");

  placeInfo.textContent =
    "First predicted place: " +
    place.displayName +
    ": " +
    place.formattedAddress;
}

init();
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

style.css

HTML

<html>
  <head>
    <title>Place Autocomplete Data API Predictions</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <div id="title"></div>
    <ul id="results"></ul>
    <p><span id="prediction"></span></p>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- prettier-ignore -->
    <script>(g=>{var h,a,k,p="The Google Maps JavaScript API",c="google",l="importLibrary",q="__ib__",m=document,b=window;b=b[c]||(b[c]={});var d=b.maps||(b.maps={}),r=new Set,e=new URLSearchParams,u=()=>h||(h=new Promise(async(f,n)=>{await (a=m.createElement("script"));e.set("libraries",[...r]+"");for(k in g)e.set(k.replace(/[A-Z]/g,t=>"_"+t[0].toLowerCase()),g[k]);e.set("callback",c+".maps."+q);a.src=`https://maps.${c}apis.com/maps/api/js?`+e;d[q]=f;a.onerror=()=>h=n(Error(p+" could not load."));a.nonce=m.querySelector("script[nonce]")?.nonce||"";m.head.append(a)}));d[l]?console.warn(p+" only loads once. Ignoring:",g):d[l]=(f,...n)=>r.add(f)&&u().then(()=>d[l](f,...n))})
        ({key: "AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg", v: "weekly"});</script>
  </body>
</html>
index.html

Prova Sample

Posiziona il completamento automatico con tipo di completamento automatico con le sessioni

Questo esempio mostra la chiamata fetchAutocompleteSuggestions() in base alle query degli utenti, mostrando un elenco di luoghi previsti in risposta e, infine, recuperando i dettagli relativi al luogo selezionato. L'esempio mostra anche l'uso di token di sessione per Raggruppa una query utente con la richiesta Place Details finale.

TypeScript

let title;
let results;
let input;
let token;

// Add an initial request body.
let request = {
    input: "",
    locationRestriction: { west: -122.44, north: 37.8, east: -122.39, south: 37.78 },
    origin: { lat: 37.7893, lng: -122.4039 },
    includedPrimaryTypes: ["restaurant"],
    language: "en-US",
    region: "us",
};

async function init() {
    token = new google.maps.places.AutocompleteSessionToken();

    title = document.getElementById('title');
    results = document.getElementById('results');
    input = document.querySelector("input");
    input.addEventListener("input", makeAcRequest);
    request = refreshToken(request) as any;
}

async function makeAcRequest(input) {
    // Reset elements and exit if an empty string is received.
    if (input.target.value == '') {
        title.innerText = '';
        results.replaceChildren();
        return;
    }

    // Add the latest char sequence to the request.
    request.input = input.target.value;

    // Fetch autocomplete suggestions and show them in a list.
    // @ts-ignore
    const { suggestions } = await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(request);

    title.innerText = 'Query predictions for "' + request.input + '"';

    // Clear the list first.
    results.replaceChildren();

    for (const suggestion of suggestions) {
        const placePrediction = suggestion.placePrediction;

        // Create a link for the place, add an event handler to fetch the place.
        const a = document.createElement('a');
        a.addEventListener('click', () => {
            onPlaceSelected(placePrediction!.toPlace());
        });
        a.innerText = placePrediction!.text.toString();

        // Create a new list element.
        const li = document.createElement('li');
        li.appendChild(a);
        results.appendChild(li);
    }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
    await place.fetchFields({
        fields: ['displayName', 'formattedAddress'],
    });
    let placeText = document.createTextNode(place.displayName + ': ' + place.formattedAddress);
    results.replaceChildren(placeText);
    title.innerText = 'Selected Place:';
    input.value = '';
    refreshToken(request);
}

// Helper function to refresh the session token.
async function refreshToken(request) {
    // Create a new session token and add it to the request.
    token = new google.maps.places.AutocompleteSessionToken();
    request.sessionToken = token;
    return request;
}

declare global {
    interface Window {
      init: () => void;
    }
  }
  window.init = init;
index.ts

JavaScript

let title;
let results;
let input;
let token;
// Add an initial request body.
let request = {
  input: "",
  locationRestriction: {
    west: -122.44,
    north: 37.8,
    east: -122.39,
    south: 37.78,
  },
  origin: { lat: 37.7893, lng: -122.4039 },
  includedPrimaryTypes: ["restaurant"],
  language: "en-US",
  region: "us",
};

async function init() {
  token = new google.maps.places.AutocompleteSessionToken();
  title = document.getElementById("title");
  results = document.getElementById("results");
  input = document.querySelector("input");
  input.addEventListener("input", makeAcRequest);
  request = refreshToken(request);
}

async function makeAcRequest(input) {
  // Reset elements and exit if an empty string is received.
  if (input.target.value == "") {
    title.innerText = "";
    results.replaceChildren();
    return;
  }

  // Add the latest char sequence to the request.
  request.input = input.target.value;

  // Fetch autocomplete suggestions and show them in a list.
  // @ts-ignore
  const { suggestions } =
    await google.maps.places.AutocompleteSuggestion.fetchAutocompleteSuggestions(
      request,
    );

  title.innerText = 'Query predictions for "' + request.input + '"';
  // Clear the list first.
  results.replaceChildren();

  for (const suggestion of suggestions) {
    const placePrediction = suggestion.placePrediction;
    // Create a link for the place, add an event handler to fetch the place.
    const a = document.createElement("a");

    a.addEventListener("click", () => {
      onPlaceSelected(placePrediction.toPlace());
    });
    a.innerText = placePrediction.text.toString();

    // Create a new list element.
    const li = document.createElement("li");

    li.appendChild(a);
    results.appendChild(li);
  }
}

// Event handler for clicking on a suggested place.
async function onPlaceSelected(place) {
  await place.fetchFields({
    fields: ["displayName", "formattedAddress"],
  });

  let placeText = document.createTextNode(
    place.displayName + ": " + place.formattedAddress,
  );

  results.replaceChildren(placeText);
  title.innerText = "Selected Place:";
  input.value = "";
  refreshToken(request);
}

// Helper function to refresh the session token.
async function refreshToken(request) {
  // Create a new session token and add it to the request.
  token = new google.maps.places.AutocompleteSessionToken();
  request.sessionToken = token;
  return request;
}

window.init = init;
index.js

CSS

/* 
 * Always set the map height explicitly to define the size of the div element
 * that contains the map. 
 */
#map {
  height: 100%;
}

/* 
 * Optional: Makes the sample page fill the window. 
 */
html,
body {
  height: 100%;
  margin: 0;
  padding: 0;
}

a {
  cursor: pointer;
  text-decoration: underline;
  color: blue;
}

input {
  width: 300px;
}

style.css

HTML

<html>
  <head>
    <title>Place Autocomplete Data API Session</title>

    <link rel="stylesheet" type="text/css" href="./style.css" />
    <script type="module" src="./index.js"></script>
  </head>
  <body>
    <input id="input" type="text" placeholder="Search for a place..." />
    <div id="title"></div>
    <ul id="results"></ul>
    <img
      class="powered-by-google"
      src="https://storage.googleapis.com/geo-devrel-public-buckets/powered_by_google_on_white.png"
      alt="Powered by Google"
    />

    <!-- 
      The `defer` attribute causes the script to execute after the full HTML
      document has been parsed. For non-blocking uses, avoiding race conditions,
      and consistent behavior across browsers, consider loading using Promises. See
      https://developers.google.com/maps/documentation/javascript/load-maps-js-api
      for more information.
      -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=init&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>
index.html

Prova Sample