API Place Autocomplete Data

L'API Place Autocomplete Data ti consente di recuperare le previsioni sui luoghi in modo programmatico, per creare esperienze di completamento automatico personalizzate con un grado di controllo più fine rispetto a quanto sia possibile con il widget di completamento automatico. In questa guida imparerai a utilizzare l'API Data di Place Autocomplete per effettuare richieste di completamento automatico in base alle query degli utenti.

L'esempio seguente mostra una semplice integrazione di compilazione automatica. Inserisci la query di ricerca, quindi fai clic su per selezionare il risultato che ti interessa.

Richieste Autocomplete

Una richiesta di completamento automatico riceve una stringa di input della query e restituisce un elenco di previsioni di luoghi. Per effettuare una richiesta di completamento automatico, chiama fetchAutocompleteSuggestions() e passa una richiesta con le proprietà necessarie. La proprietà input contiene la stringa da cercare. In un'applicazione tipica, questo valore viene aggiornato man mano che l'utente digita una query. La richiesta deve includere un sessionToken, utilizzato a fini di fatturazione.

Lo snippet seguente mostra la creazione di un corpo della richiesta e l'aggiunta di un token di sessione, quindi la chiamata a fetchAutocompleteSuggestions() per ottenere 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

Limitare le previsioni di completamento automatico

Per impostazione predefinita, la funzionalità di completamento automatico dei luoghi presenta tutti i tipi di luoghi, con un bias per le previsioni nelle vicinanze della posizione dell'utente, e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta le opzioni di completamento automatico dei luoghi per presentare previsioni più pertinenti, limitando o influenzando i risultati.

Se limiti i risultati, il widget di completamento automatico ignora quelli al di fuori dell'area di limitazione. Una pratica comune è limitare i risultati ai confini della mappa. La distorsione dei risultati consente al widget di completamento automatico di mostrare 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 partenza da cui calcolare la distanza geodetica fino alla destinazione. Se questo valore viene omesso, la distanza non viene restituita.

Utilizza la proprietà includedPrimaryTypes per specificare fino a cinque tipi di luoghi. Se non vengono specificati tipi, verranno restituiti luoghi di tutti i tipi.

Consulta il riferimento API

Ottenere i dettagli del luogo

Per restituire un oggetto Place da un risultato di previsione dei luoghi, chiama prima toPlace(), poi chiama fetchFields() sull'oggetto Place risultante (l'ID sessione della previsione dei luoghi viene incluso automaticamente). La chiamata al numero fetchFields() termina la 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 di una ricerca di completamento automatico dell'utente in una sessione distinta a fini di 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, quindi imposta la proprietà sessionToken della richiesta in modo da utilizzare i token come mostrato nel seguente snippet: 

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

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

index.js

Una sessione termina quando viene chiamato fetchFields(). Dopo aver creato l'istanza Place, non è necessario passare il token di sessione a 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 sessione successiva creando una nuova istanza di AutocompleteSessionToken.

Consigli per i token di sessione:

  • Utilizza i token di sessione per tutte le chiamate di completamento automatico dei luoghi.
  • Genera un nuovo token per ogni sessione.
  • Passa un token di sessione univoco per ogni nuova sessione. L'utilizzo dello stesso token per più sessioni comporta l'addebito di ogni richiesta singolarmente.

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

Esempio

Man mano che l'utente digita una query, viene chiamata una richiesta di completamento automatico ogni alcune tastiere (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 richiesta e tutte le richieste effettuate durante la ricerca vengono raggruppate e conteggiate come una singola richiesta. Se l'utente seleziona un luogo, la query di ricerca è disponibile senza costi e viene addebitato solo il costo della richiesta di dati del luogo. Se l'utente non effettua una selezione entro pochi minuti dall'inizio della sessione, viene addebitato solo il costo della query di ricerca.

Dal punto di vista di un'app, il flusso di eventi è il seguente:

  1. Un utente inizia a digitare una query per cercare "Parigi, Francia".
  2. Al rilevamento dell'input dell'utente, l'app crea un nuovo token di sessione, "Token A".
  3. Man mano che l'utente digita, l'API invia una richiesta di completamento automatico ogni pochi caratteri, visualizzando un nuovo elenco di potenziali risultati per ciascuno:
    "P"
    "Par"
    "Parigi"
    "Parigi, Francia"
  4. Quando l'utente effettua una selezione:
    • Tutte le richieste risultanti dalla query vengono raggruppate e aggiunte alla sessione rappresentata da "Token A", come una singola richiesta.
    • La selezione dell'utente viene conteggiata come richiesta di dettagli sui luoghi e aggiunta alla sessione rappresentata da "Token A".
  5. La sessione è conclusa e l'app elimina "Token A".
Scopri come vengono fatturate le sessioni

Codice di esempio completo

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

Previsioni di completamento automatico dei luoghi

L'esempio seguente mostra la chiamata di fetchAutocompleteSuggestions() per l'input "Tadi", quindi la chiamata di toPlace() sul primo risultato di previsione, seguita da una chiamata a fetchFields() per ottenere 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

Predizione di tipo con completamento automatico dei luoghi con le sessioni

Questo esempio mostra come chiamare fetchAutocompleteSuggestions() in base alle query degli utenti, mostrando un elenco di luoghi previsti in risposta e, infine, recuperando i dettagli del luogo selezionato. L'esempio mostra anche l'utilizzo dei token di sessione per agrupare una query dell'utente con la richiesta finale dei dettagli della sede.

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