Place Autocomplete Data API

Mit der Place Autocomplete Data API können Sie Vorhersagen zu Orten programmatisch abrufen, um eine benutzerdefinierte automatische Vervollständigung mit mehr Kontrolle zu erstellen als mit dem Widget für die automatische Vervollständigung. In diesem Leitfaden erfahren Sie, wie Sie mit der Place Autocomplete Data API automatische Vervollständigungsanfragen basierend auf Nutzeranfragen stellen.

Das folgende Beispiel zeigt eine einfache Integration für die Vorauswahl. Geben Sie eine Suchanfrage ein und klicken Sie dann auf das gewünschte Ergebnis.

Autocomplete-Anfragen

Eine Autocomplete-Anfrage nimmt einen Suchanfragestring entgegen und gibt eine Liste mit Ortsvorschlägen zurück. Rufen Sie fetchAutocompleteSuggestions() auf und übergeben Sie eine Anfrage mit den erforderlichen Properties, um eine Autocomplete-Anfrage zu stellen. Die Eigenschaft input enthält den zu suchenden String. In einer typischen Anwendung wird dieser Wert aktualisiert, während der Nutzer eine Suchanfrage eingibt. Die Anfrage muss einen sessionToken enthalten, der zu Abrechnungszwecken verwendet wird.

Im folgenden Snippet wird ein Anfragetext erstellt, ein Sitzungstoken hinzugefügt und dann fetchAutocompleteSuggestions() aufgerufen, um eine Liste der PlacePredictions 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;

index.js

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.

Werden die Ergebnisse eingeschränkt, 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 Property origin, um den Startpunkt anzugeben, von dem aus die geodätische Entfernung zum Ziel berechnet werden soll. Wird dieser Wert weggelassen, wird keine Entfernung zurückgegeben.

Mit der Property includedPrimaryTypes können Sie bis zu fünf Ortstypen angeben. Wenn keine Typen angegeben sind, werden Orte aller Typen zurückgegeben.

API-Referenz

Ortsdetails abrufen

Wenn Sie ein Place-Objekt aus einem Place Prediction-Ergebnis zurückgeben möchten, rufen Sie zuerst toPlace() und dann fetchFields() auf das resultierende Place-Objekt auf. Die Sitzungs-ID aus der Place Prediction wird automatisch eingeschlossen. Wenn Sie fetchFields() anrufen, wird die Autocomplete-Sitzung 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;
index.js

Sitzungstokens

Sitzungstokens fassen die Abfrage- und Auswahlphasen einer Nutzeranfrage zur automatischen Vervollständigung zu Abrechnungszwecken zu einer separaten Sitzung zusammen. Die Sitzung beginnt, wenn der Nutzer mit der Eingabe beginnt. Die Sitzung endet, wenn der Nutzer einen Ort auswählt und ein „Place Details“-Aufruf erfolgt.

Wenn Sie ein neues Sitzungstoken erstellen und einer Anfrage hinzufügen möchten, erstellen Sie eine Instanz von AutocompleteSessionToken und 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;

index.js

Eine Sitzung wird beendet, wenn fetchFields() aufgerufen wird. Nachdem du die Place-Instanz erstellt hast, musst du das Sitzungstoken nicht an fetchFields() weitergeben, da dies automatisch geschieht. 

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

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

Erstelle ein Sitzungstoken für die nächste Sitzung, indem du eine neue Instanz von AutocompleteSessionToken erstellst.

Empfehlungen für Sitzungstokens:

  • Verwenden Sie Sitzungstokens für alle Place Autocomplete-Aufrufe.
  • Für jede Sitzung muss ein neues Token generiert werden.
  • Für jede neue Sitzung muss ein eindeutiges Sitzungstoken übergeben werden. Wenn Sie dasselbe Token für mehr als eine Sitzung verwenden, wird jede Anfrage separat in Rechnung gestellt.

Sie können das Autocomplete-Sitzungstoken optional aus einer Anfrage auslassen. Wenn das Sitzungstoken weggelassen wird, wird jede Anfrage separat abgerechnet. Dadurch wird die SKU Autocomplete – Per Request ausgelöst. Wenn Sie ein Sitzungstoken wiederverwenden, wird die Sitzung als ungültig betrachtet und die Anfragen werden so berechnet, als wäre kein Sitzungstoken angegeben worden.

Beispiel

Während der Nutzer eine Suchanfrage eingibt, wird alle paar Tastenanschläge (nicht pro Zeichen) eine Autocomplete-Anfrage aufgerufen und eine Liste möglicher Ergebnisse zurückgegeben. Wenn der Nutzer eine Auswahl in der Ergebnisliste trifft, wird die Auswahl als Anfrage gezählt. Alle während der Suche getätigten Anfragen werden zusammengefasst und als einzelne Anfrage gezählt. Wenn der Nutzer einen Ort auswählt, ist die Suchanfrage kostenlos und es wird nur die Anfrage für Ortsdaten berechnet. 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 Ablauf so aus:

  1. Ein Nutzer beginnt, eine Suchanfrage für „Paris, Frankreich“ einzugeben.
  2. Wenn die App Nutzereingaben erkennt, erstellt sie ein neues Sitzungstoken, „Token A“.
  3. Während der Nutzer tippt, sendet die API alle paar Zeichen eine Anfrage für die automatische Vervollständigung und zeigt für jede Anfrage eine neue Liste mit möglichen Ergebnissen an:
    „P“
    „Par“
    „Paris,“
    „Paris, Fr“
  4. Wenn der Nutzer eine Auswahl trifft:
    • Alle Anfragen, die aus der Abfrage resultieren, werden gruppiert und der Sitzung, die durch „Token A“ dargestellt wird, als einzelne Anfrage hinzugefügt.
    • Die Auswahl des Nutzers wird als „Place Details“-Anfrage gezählt und der Sitzung mit dem Token „A“ hinzugefügt.
  5. Die Sitzung ist beendet und die App verwirft „Token A“.
Weitere Informationen zur Abrechnung von Sitzungen

Vollständiges Codebeispiel

Dieser Abschnitt enthält vollständige Beispiele für die Verwendung der Place Autocomplete Data API .

Automatische Vervollständigung von Orten

Im folgenden Beispiel wird fetchAutocompleteSuggestions() für die Eingabe „Tadi“ aufgerufen und dann toPlace() für das erste Vorhersageergebnis. Anschließend wird fetchFields() aufgerufen, 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();
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

Testbeispiel

Place Autocomplete-Eingabevorschläge mit Sitzungen verknüpfen

In diesem Beispiel wird gezeigt, wie fetchAutocompleteSuggestions() basierend auf Nutzerabfragen aufgerufen wird, um eine Liste mit vorhergesagten Orten anzuzeigen und schließlich Ortsdetails für den ausgewählten Ort abzurufen. Das Beispiel zeigt auch die Verwendung von Sitzungstokens, um eine Nutzerabfrage mit der endgültigen „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;
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

Testbeispiel