L'API Place Autocomplete Data consente di recuperare le previsioni dei luoghi in modo programmatico, per creare esperienze di completamento automatico personalizzate con un maggior grado di controllo rispetto al widget di completamento automatico. In questa guida imparerai a utilizzare l'API Place Autocomplete Data per effettuare richieste di completamento automatico in base alle query degli utenti.
L'esempio seguente mostra una semplice integrazione type-ahead. Inserisci la query di ricerca, quindi fai clic per selezionare il risultato che ti interessa.
Richieste Autocomplete
Una richiesta di completamento automatico accetta una stringa di input di query e restituisce un elenco di previsioni sui 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
quando l'utente digita una query. La richiesta deve includere un elemento sessionToken, che viene 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;
Vincola previsioni di Completamento automatico
Per impostazione predefinita, il completamento automatico di Place Autocomplete presenta tutti i tipi di luogo, solo per previsioni relative alla località in cui si trova l'utente, e recupera tutti i campi di dati disponibili per il luogo selezionato dall'utente. Imposta le opzioni di Place Autocomplete per presentare previsioni più pertinenti limitando o differenziando i risultati.
Se limiti i risultati, il widget di completamento automatico ignora i risultati che si trovano al di fuori dell'area di limitazione. È prassi comune limitare i risultati ai limiti della mappa. La differenziazione 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 questa area.
Utilizza la proprietà origin per specificare il punto di partenza da cui calcolare la distanza geodetica dalla 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 viene specificato nessun tipo, verranno restituiti luoghi di tutti i tipi.
Visualizza i dettagli del luogo
Per restituire un oggetto Place da un risultato della previsione di un luogo, chiama prima toPlace(), quindi chiama fetchFields() sull'oggetto Place risultante (l'ID sessione della previsione della posizione viene incluso automaticamente). La chiamata a 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;
Token di sessione
I token di sessione raggruppano le fasi di query e selezione della ricerca con completamento automatico di un utente in una sessione discreta ai fini della fatturazione. La sessione inizia quando l'utente inizia a digitare. La sessione si conclude 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 nello snippet seguente:
// Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. // @ts-ignore request.sessionToken = token;
Una sessione si conclude quando viene chiamato fetchFields(). Dopo aver creato l'istanza Place, non è necessario passare il token di sessione a fetchFields() perché viene gestito automaticamente.
await place.fetchFields({
fields: ["displayName", "formattedAddress"],
});
await place.fetchFields({
fields: ['displayName'],
});
Crea un token di sessione per la prossima sessione creando una nuova istanza di AutocompleteSessionToken.
Suggerimenti sui token di sessione:
- Utilizza i token di sessione per tutte le chiamate a Place Autocomplete.
- Genera un nuovo token per ogni sessione.
- Passa un token di sessione univoco per ogni nuova sessione. Se utilizzi lo stesso token per più sessioni, ogni richiesta verrà fatturata singolarmente.
Facoltativamente, puoi omettere da una richiesta il token della sessione di completamento automatico. Se il token di sessione viene omesso, ogni richiesta viene fatturata separatamente, attivando lo SKU Autocomplete - Per Request. 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
Quando l'utente digita una query, viene richiamata una richiesta di completamento automatico a intervalli di pochi tasti (non per carattere) e viene restituito un elenco dei possibili risultati. Quando l'utente effettua una selezione dall'elenco dei risultati, la selezione viene conteggiata come una 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 aggiuntivi e viene addebitata solo la richiesta di dati del luogo. Se l'utente non effettua una selezione entro pochi minuti dall'inizio della sessione, viene addebitata solo la query di ricerca.
Dal punto di vista di un'app, il flusso di eventi è il seguente:
- Un utente inizia a digitare una query per cercare "Parigi, Francia".
- Una volta rilevato l'input dell'utente, l'app crea un nuovo token di sessione "Token A".
- Quando l'utente digita, l'API effettua una richiesta di completamento automatico a intervalli di pochi
caratteri, mostrando un nuovo elenco di risultati potenziali per ciascun
carattere:
"P"
"Par"
"Parigi,"
"Parigi, Fr"
- Quando l'utente effettua una selezione:
- Tutte le richieste derivanti dalla query vengono raggruppate e aggiunte alla sessione rappresentata dal "token A", come singola richiesta.
- La selezione dell'utente viene conteggiata come una richiesta di Dettagli del luogo e aggiunta alla sessione rappresentata dal "Token A".
- La sessione è terminata e l'app ignora "Token A".
Esempio di codice completo
Questa sezione contiene esempi completi che mostrano come utilizzare l'API Place Autocomplete Data .Posiziona previsioni di completamento automatico
L'esempio seguente mostra la chiamata a
fetchAutocompleteSuggestions()
per l'input "Tadi", poi chiamata toPlace()
al primo risultato della previsione, seguita da una chiamata a fetchFields() per ottenere i dettagli sul 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();
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();
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;
}
HTML
<html>
<head>
<title>Place Autocomplete Data API 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>
<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>
Prova Sample
Inserisci type-ahead di completamento automatico con sessioni
Questo esempio mostra la chiamata a fetchAutocompleteSuggestions() in base alle query degli utenti, la visualizzazione di un elenco di luoghi previsti in risposta e, infine, il recupero dei dettagli del luogo per il luogo selezionato. L'esempio mostra anche l'utilizzo di token di sessione per raggruppare una query utente con la richiesta finale Place Details.
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;
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;
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;
}
HTML
<html>
<head>
<title>Place Autocomplete Data API Session</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>
<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>