Place Autocomplete-Daten-API

Mit der Place Autocomplete Data API können Sie Ortsvorschläge abrufen programmgesteuert, um benutzerdefinierte automatische Vervollständigungen mit mehr Kontrolle zu erstellen als mit dem Widget für die automatische Vervollständigung möglich. In diesem Leitfaden erfahren Sie, wie Sie die Place Autocomplete Data API, um Anfragen zur automatischen Vervollständigung basierend auf dem Nutzer zu stellen Abfragen.

Das folgende Beispiel zeigt eine einfache Einbindung mit automatischer Vervollständigung. Geben Sie Ihre Suchanfrage ein und klicken Sie auf um das gewünschte Ergebnis auszuwählen.

<ph type="x-smartling-placeholder"></ph> <ph type="x-smartling-placeholder">

Autocomplete-Anfragen

Eine Anfrage zur automatischen Vervollständigung verwendet einen Abfrage-Eingabestring und gibt eine Liste mit Ortsvorschlägen zurück. Bis eine Anfrage zur automatischen Vervollständigung stellen, fetchAutocompleteSuggestions() aufrufen und übergeben eine Anfrage mit den erforderlichen Attributen. Die input property enthält die Zeichenfolge, nach der gesucht werden soll. In einer typischen Anwendung wird dieser Wert so aktualisiert: wenn der Nutzer eine Suchanfrage eingibt. Die Anfrage sollte Folgendes enthalten: sessionToken, das zu Abrechnungszwecken verwendet wird.

Das folgende Snippet zeigt, wie Sie einen Anfragetext erstellen, ein Sitzungstoken hinzufügen und dann fetchAutocompleteSuggestions(), um eine Liste der 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

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 Sie die Ergebnisse einschränken, ignoriert das Autocomplete-Widget alle Ergebnisse, die außerhalb der Beschränkungsbereichs. 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 für die Berechnung anzugeben. geodätische Entfernung zum Ziel. Wenn dieser Wert weggelassen wird, wird die Entfernung nicht zurückgegeben.

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

Siehe API-Referenz

Ortsdetails abrufen

So geben Sie ein Place-Objekt zurück: -Objekt aus einem Ortsvorschlagsergebnis zu erhalten, rufen Sie zuerst toPlace() auf, dann fetchFields() aufrufen für das resultierende Place-Objekt (die Sitzungs-ID der Ortsvervollständigung ist automatisch enthalten). Durch den Aufruf von fetchFields() wird der Sitzung für die automatische Vervollständigung. 

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 gruppieren die Abfrage- und Auswahlphasen einer Nutzersuche mit automatischer Vervollständigung in einem diskrete Sitzung zu Abrechnungszwecken Die Sitzung beginnt, sobald der Nutzer mit der Eingabe beginnt. Die Sitzung wird beendet, wenn der Nutzer einen Ort auswählt und die Funktion „Place Details“ aufgerufen wird.

Um ein neues Sitzungstoken zu erstellen und einer Anfrage hinzuzufügen, erstellen Sie eine Instanz von AutocompleteSessionToken, und lege dann sessionToken fest. der Anfrage, um die Tokens zu verwenden, 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 Sie die Instanz Place erstellt haben, müssen Sie die Sitzung nicht übergeben. Token an fetchFields(), da dies automatisch verarbeitet wird. 

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

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

Legen Sie ein Sitzungstoken für die nächste Sitzung fest. Erstellen Sie dazu eine neue Instanz von AutocompleteSessionToken.

Empfehlungen für Sitzungstokens:

  • Verwenden Sie für alle „Place Autocomplete“-Aufrufe Sitzungstokens.
  • Generieren Sie für jede Sitzung ein neues Token.
  • Übergeben Sie für jede neue Sitzung ein eindeutiges Sitzungstoken. Das gleiche Token für mehr als eine Sitzung verwenden wird jede Anfrage einzeln abgerechnet.

Sie können das Sitzungstoken für die automatische Vervollständigung in einer Anfrage auch weglassen. Wenn das Sitzungstoken wird jede Anfrage separat abgerechnet. Dadurch wird der Autocomplete – Per Request Artikelnummer Wenn Sie ein Sitzungstoken wiederverwenden, wird die Sitzung als ungültig betrachtet und die Anfragen werden in Rechnung gestellt so als wäre kein Sitzungstoken angegeben.

Beispiel

Während der Nutzer eine Anfrage eingibt, wird alle paar Mal eine Anfrage zur automatischen Vervollständigung aufgerufen. Tastenanschlägen (nicht pro Zeichen) und eine Liste möglicher Ergebnisse wird zurückgegeben. Wenn der Nutzer eine Auswahl in der Ergebnisliste trifft, wird diese Auswahl gezählt als und alle während der Suche gestellten Anfragen werden gebündelt und wird als einzelne Anfrage gezählt. Wählt der Nutzer einen Ort aus, lautet die Suchanfrage kostenlos zur Verfügung. Nur die Datenanfrage für den Ort wird in Rechnung gestellt. Macht der Nutzer wenige Minuten nach Beginn der Sitzung ausgewählt werden, in Rechnung gestellt.

Aus der Perspektive einer App verläuft der Ereignisfluss wie folgt:

  1. Ein Nutzer beginnt mit der Eingabe einer Suchanfrage, um nach „Paris, Frankreich“ zu suchen.
  2. Nach Erkennung von Nutzereingaben erstellt die App eine neue Sitzung „Token A“.
  3. Während der Nutzer tippt, führt die API alle paar Mal eine Anfrage zur automatischen Vervollständigung durch. Zeichen, wodurch jeweils eine neue Liste mit möglichen Ergebnissen angezeigt wird:
    „P“
    „Par“
    „Paris“
    „Paris, Fr“
  4. Wenn der Nutzer eine Auswahl trifft: <ph type="x-smartling-placeholder">
      </ph>
    • Alle aus der Abfrage resultierenden Anfragen werden gruppiert und dem Sitzung, dargestellt durch „Token A“, als einzelne Anfrage.
    • Die Auswahl des Nutzers wird als Ortsdetailanfrage gezählt und hinzugefügt für die Sitzung, die durch „Token A“ dargestellt wird.
  5. Die Sitzung wird beendet und die App verwirft das Token A.
Weitere Informationen zur Abrechnung von Sitzungen

Vollständiges Codebeispiel

Dieser Abschnitt enthält vollständige Beispiele, die die Verwendung des Place Autocomplete Data API veranschaulichen .

Vervollständigungen bei der automatischen Vervollständigung von Orten

Im folgenden Beispiel sehen Sie, fetchAutocompleteSuggestions() für die Eingabe „Tadi“ und ruft dann toPlace() auf auf das erste Vervollständigungsergebnis, gefolgt von einem Aufruf 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();
index.ts
 <ph type="x-smartling-placeholder">

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
 <ph type="x-smartling-placeholder">

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

Automatische Vervollständigung bei Sitzungen mit automatischer Vervollständigung einfügen

In diesem Beispiel wird veranschaulicht, fetchAutocompleteSuggestions() basierend auf Nutzeranfragen, die als Antwort eine Liste mit Ortsvorschlägen anzeigt und schließlich Ortsdetails für den ausgewählten Ort. Das Beispiel zeigt auch die Verwendung von Sitzungstokens, Mit der letzten „Place Details“-Anfrage können Sie eine Nutzeranfrage 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
 <ph type="x-smartling-placeholder">

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
 <ph type="x-smartling-placeholder">

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