Mit der Place Autocomplete Data API können Sie Ortsvorschläge programmatisch abrufen und so benutzerdefinierte automatische Vervollständigungen erstellen, die mehr Kontrolle haben als mit dem Widget für die automatische Vervollständigung. In diesem Leitfaden erfahren Sie, wie Sie mit der Place Autocomplete Data API Anfragen für die automatische Vervollständigung anhand von Nutzerabfragen stellen.
Das folgende Beispiel zeigt eine einfache Typ-Ahead-Integration. Geben Sie Ihre Suchanfrage ein und klicken Sie dann auf das gewünschte Ergebnis.
Autocomplete-Anfragen
Bei einer Anfrage zur automatischen Vervollständigung wird anhand eines Eingabestrings für die Abfrage eine Liste mit Vorschlägen für Orte zurückgegeben. Für eine Anfrage zur automatischen Vervollständigung rufen Sie fetchAutocompleteSuggestions() auf und übergeben eine Anfrage mit den erforderlichen Attributen. Die Eigenschaft input enthält den zu suchenden String. In einer typischen Anwendung wird dieser Wert aktualisiert, wenn der Nutzer eine Abfrage eingibt. Die Anfrage sollte eine sessionToken enthalten, die zu Abrechnungszwecken verwendet wird.
Das folgende Snippet zeigt, wie Sie einen Anfragetext erstellen, ein Sitzungstoken hinzufügen und dann fetchAutocompleteSuggestions() aufrufen, um eine Liste von PlacePrediction abzurufen.
// 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;
Automatische Vervollständigung einschränken
Standardmäßig zeigt Place Autocomplete sämtliche Ortstypen an. Dabei werden die Vorschläge nach der Nähe zum Nutzerstandort gewichtet. Es werden alle verfügbaren Datenfelder für den vom Nutzer ausgewählten Ort abgerufen. Sie können die Optionen für Place Autocomplete so festlegen, dass relevantere Vorschläge angezeigt werden. Dazu schränken Sie die Ergebnisse ein oder wenden eine Gewichtung an.
Wenn die Ergebnisse eingeschränkt werden, ignoriert das Autocomplete-Widget alle Ergebnisse, die außerhalb des festgelegten Bereichs liegen. Häufig werden die Ergebnisse auf die Kartengrenzen beschränkt. Wenn Sie eine Gewichtung anwenden, zeigt das Autocomplete-Widget Ergebnisse innerhalb des angegebenen Bereichs an, einige können jedoch auch außerhalb liegen.
Verwenden Sie die Eigenschaft origin, um den Startpunkt anzugeben, von dem aus die geodätische Entfernung zum Ziel berechnet werden soll. Wenn dieser Wert weggelassen wird, wird keine Entfernung zurückgegeben.
Mit der Eigenschaft includedPrimaryTypes können Sie bis zu fünf Ortstypen angeben.
Wenn keine Typen angegeben sind, werden Orte aller Typen zurückgegeben.
Ortsdetails abrufen
Wenn Sie ein Place-Objekt aus einem Ergebnis für die Ortsvorhersage zurückgeben möchten, müssen Sie zuerst toPlace() und dann fetchFields() für das resultierende Place-Objekt aufrufen. Die Sitzungs-ID der Ortsvorhersage wird automatisch eingefügt. Durch den Aufruf von fetchFields() wird die Sitzung mit automatischer Vervollständigung beendet.
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;
Sitzungstokens
Sitzungstokens fassen die Abfrage- und Auswahlphasen einer automatischen Vervollständigung durch den Nutzer zu Abrechnungszwecken zu einer separaten Sitzung zusammen. Die Sitzung beginnt, wenn der Nutzer zu tippen beginnt. Die Sitzung wird beendet, wenn der Nutzer einen Ort auswählt und eine Place Details-Anfrage aufgerufen wird.
Um ein neues Sitzungstoken zu erstellen und einer Anfrage hinzuzufügen, erstellen Sie eine Instanz von AutocompleteSessionToken. Legen Sie dann das Attribut sessionToken der Anfrage so fest, dass die Tokens verwendet werden, wie im folgenden Snippet gezeigt:
// Create a session token. const token = new AutocompleteSessionToken(); // Add the token to the request. // @ts-ignore request.sessionToken = token;
Eine Sitzung wird beendet, wenn fetchFields() aufgerufen wird. Nach dem Erstellen der Place-Instanz müssen Sie das Sitzungstoken nicht an fetchFields() übergeben, da dies automatisch verarbeitet wird.
await place.fetchFields({
fields: ["displayName", "formattedAddress"],
});
await place.fetchFields({
fields: ['displayName'],
});
Erstellen Sie ein Sitzungstoken für die nächste Sitzung, indem Sie eine neue Instanz von AutocompleteSessionToken erstellen.
Empfehlungen für Sitzungstokens:
- Verwenden Sie Sitzungstokens für alle Place Autocomplete-Aufrufe.
- Generieren Sie für jede Sitzung ein neues Token.
- Übergeben Sie für jede neue Sitzung ein eindeutiges Sitzungstoken. Wenn Sie dasselbe Token für mehr als eine Sitzung verwenden, wird jede Anfrage einzeln in Rechnung gestellt.
Sie können das Sitzungstoken für die automatische Vervollständigung optional in einer Anfrage weglassen. Ohne das Sitzungstoken wird jede Anfrage separat abgerechnet und die SKU Autocomplete – Per Request wird ausgelöst. Wenn Sie ein Sitzungstoken wiederverwenden, wird die Sitzung als ungültig betrachtet und die Anfragen werden so abgerechnet, als wäre kein Sitzungstoken angegeben worden.
Beispiel
Während der Nutzer eine Abfrage eingibt, wird eine Anfrage zur automatischen Vervollständigung alle paar Tastenanschläge (nicht pro Zeichen) aufgerufen und eine Liste möglicher Ergebnisse zurückgegeben. Trifft der Nutzer eine Auswahl aus der Ergebnisliste, gilt diese Auswahl als Anfrage. Alle während der Suche gestellten Anfragen werden gruppiert und als einzelne Anfrage gezählt. Wenn der Nutzer einen Ort auswählt, ist die Suchanfrage kostenlos verfügbar und nur die Ortsdatenanfrage wird in Rechnung gestellt. Wenn der Nutzer innerhalb weniger Minuten nach Beginn der Sitzung keine Auswahl trifft, wird nur die Suchanfrage in Rechnung gestellt.
Aus Sicht einer App sieht der Ereignisfluss wie folgt aus:
- Ein Nutzer beginnt mit der Eingabe einer Suchanfrage, um nach "Paris, Frankreich" zu suchen.
- Nachdem die Nutzereingabe erkannt wurde, erstellt die Anwendung ein neues Sitzungstoken „Token A“.
- Während der Nutzer eingibt, stellt die API nach wenigen Zeichen eine Anfrage zur automatischen Vervollständigung. Dabei wird jeweils eine neue Liste mit möglichen Ergebnissen angezeigt:
„P“
„Par“
„Paris“,
„Paris, Fr“
- Wenn der Nutzer eine Auswahl trifft:
- Alle Anfragen, die aus der Abfrage resultieren, werden gruppiert und der durch "Token A" dargestellten Sitzung als einzelne Anfrage hinzugefügt.
- Die Auswahl des Nutzers wird als „Place Details“-Anfrage gezählt und der durch „Token A“ dargestellten Sitzung hinzugefügt.
- Die Sitzung ist beendet und die App verwirft Token A.
Vollständiges Codebeispiel
Dieser Abschnitt enthält vollständige Beispiele zur Verwendung der Place Autocomplete Data API .Automatisch vervollständigte Orte
Im folgenden Beispiel wird gezeigt, wie fetchAutocompleteSuggestions() für die Eingabe „Tadi“ aufgerufen wird und dann toPlace() für das erste Vorhersageergebnis aufgerufen wird, gefolgt von fetchFields(), um Ortsdetails abzurufen.
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>
Testbeispiel
Place Autocomplete-Eingabe mit Sitzungen
In diesem Beispiel wird anhand von Nutzerabfragen fetchAutocompleteSuggestions() aufgerufen, als Antwort eine Liste mit vorhergesagten Orten angezeigt und schließlich Ortsdetails für den ausgewählten Ort abgerufen. Im Beispiel wird auch gezeigt, wie Sitzungstokens verwendet werden, um eine Nutzerabfrage mit der abschließenden Place Details-Anfrage zu gruppieren.
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>