Place Autocomplete

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.
Plattform auswählen: Android iOS JavaScript Webdienst

Einführung

Die automatische Vervollständigung ist ein Feature der Places-Bibliothek in der Maps JavaScript API. Sie können die automatische Vervollständigung verwenden, um den Anwendungen das Google Maps-Suchfeld vorzugeben. Der Dienst für die automatische Vervollständigung kann vollständige Wörter und Teilstrings abgleichen, sodass Ortsnamen, Adressen und Plus Codes aufgelöst werden. Anwendungen können daher Abfragen senden, während der Nutzer tippt, um ortsbezogene Vervollständigungen bereitzustellen.

Erste Schritte

Bevor Sie die Places Library in der Maps JavaScript API verwenden, muss die Places API in der Google Cloud Console in dem Projekt aktiviert sein, das Sie für die Maps JavaScript API eingerichtet haben.

So zeigen Sie die Liste der aktivierten APIs an:

  1. Rufen Sie die Google Cloud Console auf.
  2. Klicken Sie auf die Schaltfläche Projekt auswählen, wählen Sie das Projekt aus, das Sie für die Maps JavaScript API eingerichtet haben, und klicken Sie dann auf Öffnen.
  3. Suchen Sie im Dashboard in der Liste der APIs nach Places API.
  4. Wenn die API in der Liste angezeigt wird, sind Sie startbereit. Wenn die API nicht aufgeführt ist, aktivieren Sie sie:
    1. Wähle oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Alternativ kannst du im Menü auf der linken Seite Mediathek auswählen.
    2. Suchen Sie nach der Places API und wählen Sie sie in der Ergebnisliste aus.
    3. Wähle AKTIVIEREN aus. Wenn der Vorgang abgeschlossen ist, wird Places API in der Liste der APIs auf dem Dashboard angezeigt.

Laden der Bibliothek

Der Places-Dienst ist eine eigenständige Bibliothek, die unabhängig vom Code der Maps JavaScript API ist. Wenn Sie die in dieser Bibliothek enthaltenen Funktionen verwenden möchten, müssen Sie sie zuerst mit dem Parameter libraries in der Bootstrap-URL der Maps API laden:

<script async
    src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places&callback=initMap">
</script>

Weitere Informationen findest du unter Mediatheken.

Übersicht über Klassen

Die API bietet zwei Arten von Widgets zur automatischen Vervollständigung, die du über die Klassen Autocomplete und SearchBox hinzufügen kannst. Darüber hinaus können Sie die Klasse AutocompleteService verwenden, um Ergebnisse der automatischen Vervollständigung programmatisch abzurufen (siehe Maps JavaScript API-Referenz: AutocompleteService-Klasse).

Nachfolgend sind die verfügbaren Klassen zusammengefasst:

  • Autocomplete fügt deiner Webseite ein Texteingabefeld hinzu und überwacht dieses Feld auf Zeicheneingaben. Während der Nutzer Text eingibt, werden automatische Vervollständigungen in Form einer Drop-down-Auswahlliste zurückgegeben. Wenn der Nutzer einen Ort aus der Liste auswählt, werden Informationen über den Ort an das Objekt zur automatischen Vervollständigung zurückgegeben und können von deiner Anwendung abgerufen werden. Weitere Informationen
    Ein Textfeld mit automatischer Vervollständigung und die Auswahlliste mit Ortsvorhersagen, die angezeigt wird, wenn der Nutzer die Suchanfrage eingibt.
    Abbildung 1: Textfeld mit automatischer Vervollständigung und Auswahlliste
    Ein ausgefülltes Adressformular.
    Abbildung 2: Ausgefülltes Adressformular
  • SearchBox fügt deiner Webseite ein Texteingabefeld hinzu, ähnlich wie Autocomplete. Es bestehen folgende Unterschiede:
    • Der Hauptunterschied besteht in den Ergebnissen, die in der Auswahlliste angezeigt werden. SearchBox stellt eine erweiterte Liste mit Vervollständigungen bereit. Diese können Orte (wie in der Places API definiert) und vorgeschlagene Suchbegriffe enthalten. Wenn der Nutzer beispielsweise „pizza in berlin“ eingibt, kann die Auswahlliste den Text „pizza in berlin“ und die Namen verschiedener Pizzerien enthalten.
    • SearchBox bietet weniger Optionen als Autocomplete zum Einschränken der Suche. Bei Ersterer kannst du die Suche auf ein bestimmtes LatLngBounds-Objekt abstimmen. In letzterem Fall können Sie die Suche auf ein bestimmtes Land und bestimmte Ortstypen beschränken und die Grenzen festlegen. Weitere Informationen finden Sie unten.
    Ein ausgefülltes Adressformular.
    Abbildung 3: Ein Suchfeld zeigt Suchbegriffe und Ortsvorhersagen an.
    Weitere Informationen
  • Sie können ein AutocompleteService-Objekt erstellen, um Vorhersagen programmatisch abzurufen. Rufe getPlacePredictions() auf, um übereinstimmende Orte abzurufen, oder getQueryPredictions(), um übereinstimmende Orte und vorgeschlagene Suchbegriffe abzurufen. Hinweis: AutocompleteService fügt keine UI-Steuerelemente hinzu. Stattdessen wird mit der obigen Methode ein Array mit Vorhersageobjekten ausgegeben. Jedes Vorhersageobjekt enthält den Text der Vorhersage sowie Referenzinformationen und Details dazu, wie das Ergebnis mit der Nutzereingabe übereinstimmt. Weitere Informationen

Autocomplete-Widget hinzufügen

Das Autocomplete-Widget erstellt ein Texteingabefeld auf deiner Webseite, liefert Vervollständigungen für Orte in einer UI-Auswahlliste und gibt Ortsdetails als Antwort auf eine getPlace()-Anfrage zurück. Jeder Eintrag in der Auswahlliste entspricht einem einzelnen Ort (wie in der Places API definiert).

Der Konstruktor Autocomplete verwendet zwei Argumente:

  • Ein HTML-input-Element des Typs text. Dies ist das Eingabefeld, das der Dienst zur automatischen Vervollständigung überwacht und an den die Ergebnisse angehängt werden.
  • Ein optionales Argument AutocompleteOptions, das die folgenden Attribute enthalten kann:
    • Ein Array mit Daten fields, die in die Antwort Place Details für die vom Nutzer ausgewählten PlaceResult aufgenommen werden sollen. Wenn das Attribut nicht festgelegt ist oder ['ALL'] übergeben wird, werden alle verfügbaren Felder zurückgegeben und in Rechnung gestellt. Dies wird für Produktionsbereitstellungen nicht empfohlen. Eine Liste der Felder finden Sie unter PlaceResult.
    • Ein Array von types, das einen expliziten Typ oder eine Typsammlung angibt, wie in den unterstützten Typen aufgeführt. Wenn kein Typ angegeben ist, werden alle Typen zurückgegeben.
    • bounds ist ein google.maps.LatLngBounds-Objekt, das den Bereich angibt, in dem nach Orten gesucht wird. Die Ergebnisse sind nach Orten innerhalb dieser Grenzen gewichtet, aber nicht darauf beschränkt.
    • strictBounds ist eine boolean, die angibt, ob die API nur die Orte zurückgeben soll, die sich genau in der Region befinden, die durch die angegebene bounds definiert wird. Die API gibt keine Ergebnisse außerhalb dieser Region zurück, selbst wenn sie mit der Nutzereingabe übereinstimmen.
    • Mit componentRestrictions können Ergebnisse auf bestimmte Gruppen beschränkt werden. Derzeit können Sie mit componentRestrictions nach bis zu fünf Ländern filtern. Länder müssen als zweistelliger, nach ISO 3166-1 Alpha-2 kompatibler Ländercode übergeben werden. Es müssen mehrere Länder als Liste mit Ländercodes übergeben werden.

      Hinweis:Wenn du unerwartete Ergebnisse mit einem Ländercode erhältst, überprüfe, ob du einen Code verwendest, der die Länder, abhängigen Gebiete und besonderen geografischen Gebiete enthält, die du beabsichtigt hast. Codeinformationen findest du unter Wikipedia: Liste der ISO 3166-Ländercodes oder auf der ISO-Onlineseitenplattform.

    • Mit placeIdOnly kann das Autocomplete-Widget angewiesen werden, nur Place IDs abzurufen. Beim Aufrufen von getPlace() für das Autocomplete-Objekt werden für die verfügbare PlaceResult nur die Properties place id, types und name festgelegt. Sie können die zurückgegebene Orts-ID mit Aufrufen der Places-, Geocoding-, Directions- oder Distance Matrix-Dienste verwenden.

Autocomplete-Vervollständigungen einschränken

Standardmäßig werden in Place Autocomplete alle Ortstypen angezeigt, die nach Vorhersagen in der Nähe des Standorts des Nutzers abgestimmt sind. Es werden alle verfügbaren Datenfelder für den ausgewählten Ort abgerufen. Legen Sie Place Autocomplete-Optionen fest, um basierend auf Ihrem Anwendungsfall relevantere Vervollständigungen anzuzeigen.

Optionen bei Bau festlegen

Der Konstruktor Autocomplete akzeptiert einen AutocompleteOptions-Parameter, um beim Erstellen des Widgets Einschränkungen festzulegen. Im folgenden Beispiel werden die Optionen bounds, componentRestrictions und types festgelegt, um Orte vom Typ establishment anzufordern. Dabei werden die Orte innerhalb des angegebenen geografischen Gebiets bevorzugt und die Vorhersagen auf Orte innerhalb der USA beschränkt. Mit der Option fields geben Sie an, welche Informationen zum ausgewählten Ort zurückgegeben werden sollen.

Rufe setOptions() auf, um den Wert einer Option für ein vorhandenes Widget zu ändern.

TypeScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input") as HTMLInputElement;
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};

const autocomplete = new google.maps.places.Autocomplete(input, options);

JavaScript

const center = { lat: 50.064192, lng: -130.605469 };
// Create a bounding box with sides ~10km away from the center point
const defaultBounds = {
  north: center.lat + 0.1,
  south: center.lat - 0.1,
  east: center.lng + 0.1,
  west: center.lng - 0.1,
};
const input = document.getElementById("pac-input");
const options = {
  bounds: defaultBounds,
  componentRestrictions: { country: "us" },
  fields: ["address_components", "geometry", "icon", "name"],
  strictBounds: false,
  types: ["establishment"],
};
const autocomplete = new google.maps.places.Autocomplete(input, options);

Datenfelder angeben

Geben Sie Datenfelder an, damit Ihnen keine Places Data SKUs in Rechnung gestellt werden, die Sie nicht benötigen. Füge das Attribut fields in den AutocompleteOptions ein, das an den Widget-Konstruktor übergeben wird (wie im vorherigen Beispiel), oder rufe setFields() für ein vorhandenes Autocomplete-Objekt auf.

autocomplete.setFields(["place_id", "geometry", "name"]);

Verzerrungen und Suchbereichgrenzen für die automatische Vervollständigung definieren

Sie können die Ergebnisse der automatischen Vervollständigung so beeinflussen, dass ein ungefährer Standort oder Bereich ermittelt wird. Das geht so:

  • Legen Sie die Grenzen beim Erstellen des Autocomplete-Objekts fest.
  • Grenzen eines vorhandenen Autocomplete ändern.
  • Legen Sie die Grenzen auf den Darstellungsbereich der Karte fest.
  • Suche auf die Grenzen beschränken
  • Beschränken Sie die Suche auf ein bestimmtes Land.

Das vorherige Beispiel zeigt, wie beim Erstellen Grenzen festgelegt werden. Die folgenden Beispiele zeigen die anderen Gewichtungstechniken.

Grenzen eines bestehenden Objekts „Autocomplete“ ändern

Rufe setBounds() auf, um den Suchbereich für einen vorhandenen Autocomplete in rechteckige Begrenzungen zu ändern.

TypeScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);

JavaScript

const southwest = { lat: 5.6108, lng: 136.589326 };
const northeast = { lat: 61.179287, lng: 2.64325 };
const newBounds = new google.maps.LatLngBounds(southwest, northeast);

autocomplete.setBounds(newBounds);
Grenzen auf den Darstellungsbereich der Karte festlegen

Verwende bindTo(), um die Ergebnisse auf den Darstellungsbereich der Karte auszurichten, auch wenn dieser sich ändert.

TypeScript

autocomplete.bindTo("bounds", map);

JavaScript

autocomplete.bindTo("bounds", map);

Mit unbind() können Sie die Verknüpfung der automatischen Vervollständigungen mit dem Darstellungsbereich der Karte aufheben.

TypeScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

JavaScript

autocomplete.unbind("bounds");
autocomplete.setBounds({ east: 180, west: -180, north: 90, south: -90 });

Beispiel ansehen

Suche auf aktuelle Grenzen beschränken

Legen Sie die Option strictBounds fest, um die Ergebnisse auf die aktuellen Grenzen zu beschränken, unabhängig davon, ob sie auf dem Darstellungsbereich der Karte oder auf rechteckigen Begrenzungen basieren.

autocomplete.setOptions({ strictBounds: true });
Vervollständigungen auf ein bestimmtes Land beschränken

Verwenden Sie die Option componentRestrictions oder rufen Sie setComponentRestrictions() auf, um die Suche mit automatischer Vervollständigung auf bis zu fünf Länder zu beschränken.

TypeScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

JavaScript

autocomplete.setComponentRestrictions({
  country: ["us", "pr", "vi", "gu", "mp"],
});

Beispiel ansehen

Ortstypen einschränken

Verwenden Sie die Option types oder rufen Sie setTypes() auf, um Vorhersagen auf bestimmte Ortstypen einzuschränken. Mit dieser Einschränkung wird ein Typ oder eine Typsammlung angegeben, wie unter Ortstypen aufgeführt. Wenn keine Einschränkung angegeben ist, werden alle Typen zurückgegeben.

Für den Wert der Option types oder den an setTypes() übergebenen Wert können Sie entweder Folgendes angeben:

  • Ein Array, das bis zu fünf Werte aus Tabelle 1 oder Tabelle 2 aus Ortstypen enthält. Beispiel:

    types: ['hospital', 'pharmacy', 'bakery', 'country']

    oder zu:

    autocomplete.setTypes(['hospital', 'pharmacy', 'bakery', 'country']);
  • Jeder Filter in Tabelle 3 aus Ortstypen. Sie können nur einen einzelnen Wert aus Tabelle 3 angeben.

In folgenden Fällen wird die Anfrage abgelehnt:

  • Sie geben mehr als fünf Typen an.
  • Sie geben alle unbekannten Typen an.
  • Sie können beliebige Typen aus Tabelle 1 oder Tabelle 2 mit einem beliebigen Filter aus Tabelle 3 kombinieren.

Die Demo für die automatische Vervollständigung von Orten veranschaulicht die Unterschiede bei den Vorhersagen zwischen verschiedenen Ortstypen.

Zur Demo

Informationen zu Orten abrufen

Wenn ein Nutzer einen Ort aus den Vervollständigungen auswählt, die an das Textfeld zur automatischen Vervollständigung angehängt sind, löst der Dienst ein place_changed-Ereignis aus. So rufen Sie Informationen zum Ort ab:

  1. Erstellen Sie einen Ereignis-Handler für das Ereignis place_changed und rufen Sie addListener() für das Objekt Autocomplete auf, um den Handler hinzuzufügen.
  2. Rufe Autocomplete.getPlace() für das Autocomplete-Objekt auf, um ein PlaceResult-Objekt abzurufen, mit dem du dann weitere Informationen zum ausgewählten Ort abrufen kannst.

Wenn ein Nutzer einen Ort auswählt, gibt die automatische Vervollständigung standardmäßig alle verfügbaren Datenfelder für den ausgewählten Ort zurück. Dann werden Ihnen die Kosten entsprechend in Rechnung gestellt. Mit Autocomplete.setFields() geben Sie an, welche Ortsdatenfelder zurückgegeben werden sollen. Weitere Informationen zum Objekt PlaceResult, einschließlich einer Liste von Ortsdatenfeldern, die Sie anfordern können. Damit Sie nicht für Daten zahlen müssen, die Sie nicht brauchen, verwenden Sie Autocomplete.setFields(), um nur die benötigten Standortdaten anzugeben.

Die Property name enthält die description aus den Vervollständigungen in Places. Weitere Informationen zu description finden Sie in der Dokumentation zur Places Autocomplete-Funktion.

Bei Adressformularen ist es hilfreich, die Adresse im strukturierten Format abzurufen. Um die strukturierte Adresse für den ausgewählten Ort zurückzugeben, rufen Sie Autocomplete.setFields() auf und geben Sie das Feld address_components an.

Im folgenden Beispiel werden die Felder in einem Adressformular mithilfe der automatischen Vervollständigung ausgefüllt.

TypeScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components as google.maps.GeocoderAddressComponent[]) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }

      case "locality":
        (document.querySelector("#locality") as HTMLInputElement).value =
          component.long_name;
        break;

      case "administrative_area_level_1": {
        (document.querySelector("#state") as HTMLInputElement).value =
          component.short_name;
        break;
      }

      case "country":
        (document.querySelector("#country") as HTMLInputElement).value =
          component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;

  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

JavaScript

function fillInAddress() {
  // Get the place details from the autocomplete object.
  const place = autocomplete.getPlace();
  let address1 = "";
  let postcode = "";

  // Get each component of the address from the place details,
  // and then fill-in the corresponding field on the form.
  // place.address_components are google.maps.GeocoderAddressComponent objects
  // which are documented at http://goo.gle/3l5i5Mr
  for (const component of place.address_components) {
    // @ts-ignore remove once typings fixed
    const componentType = component.types[0];

    switch (componentType) {
      case "street_number": {
        address1 = `${component.long_name} ${address1}`;
        break;
      }

      case "route": {
        address1 += component.short_name;
        break;
      }

      case "postal_code": {
        postcode = `${component.long_name}${postcode}`;
        break;
      }

      case "postal_code_suffix": {
        postcode = `${postcode}-${component.long_name}`;
        break;
      }
      case "locality":
        document.querySelector("#locality").value = component.long_name;
        break;
      case "administrative_area_level_1": {
        document.querySelector("#state").value = component.short_name;
        break;
      }
      case "country":
        document.querySelector("#country").value = component.long_name;
        break;
    }
  }

  address1Field.value = address1;
  postalField.value = postcode;
  // After filling the form with address components from the Autocomplete
  // prediction, set cursor focus on the second address line to encourage
  // entry of subpremise information such as apartment, unit, or floor number.
  address2Field.focus();
}

window.initAutocomplete = initAutocomplete;

Beispiel ansehen

Platzhaltertext anpassen

Das vom Dienst zur automatischen Vervollständigung erstellte Textfeld enthält standardmäßig Standardplatzhaltertext. Wenn du den Text ändern möchtest, setze das Attribut placeholder für das Element input:

<input id="searchTextField" type="text" size="50" placeholder="Anything you want!">

Hinweis: Der Standardplatzhaltertext wird automatisch lokalisiert. Wenn Sie einen eigenen Platzhalterwert angeben, müssen Sie die Lokalisierung dieses Werts in Ihrer Anwendung verarbeiten. Informationen dazu, wie die Google Maps JavaScript API die Sprache auswählt, finden Sie in der Dokumentation zur Lokalisierung.

Informationen zum Anpassen der Darstellung von Widgets finden Sie unter Stile für Autocomplete und SearchBox festlegen.

Mit SearchBox können Nutzer eine textbasierte geografische Suche ausführen, z. B. „Pizza in New York“ oder „Schuhgeschäfte in der Nähe von Roben Street“. Sie können SearchBox an ein Textfeld anhängen. Sobald Text eingegeben wird, gibt der Dienst Vorhersagen in Form einer Drop-down-Auswahlliste zurück.

SearchBox liefert eine erweiterte Liste mit Vervollständigungen, die Orte (wie in der Places API definiert) und vorgeschlagene Suchbegriffe umfassen kann. Wenn der Nutzer beispielsweise „pizza in berlin“ eingibt, kann die Auswahlliste den Text „pizza in berlin“ und die Namen verschiedener Pizzerien enthalten. Wenn ein Nutzer einen Ort aus der Liste auswählt, werden Informationen zu diesem Ort an das SearchBox-Objekt zurückgegeben und können von deiner Anwendung abgerufen werden.

Der Konstruktor SearchBox verwendet zwei Argumente:

  • Ein HTML-input-Element des Typs text. Dies ist das Eingabefeld, das der SearchBox-Dienst überwacht und an das die Ergebnisse angehängt werden.
  • Ein options-Argument, das die Property bounds enthalten kann: bounds ist ein google.maps.LatLngBounds-Objekt, das den Bereich angibt, in dem nach Orten gesucht wird. Die Ergebnisse sind nach Orten innerhalb dieser Grenzen gewichtet, aber nicht darauf beschränkt.

Im folgenden Code wird der Parameter bounds verwendet, um die Ergebnisse nach Orten innerhalb eines bestimmten geografischen Gebiets zu gewichten, der über Längen- und Breitengradkoordinaten angegeben wird.

var defaultBounds = new google.maps.LatLngBounds(
  new google.maps.LatLng(-33.8902, 151.1759),
  new google.maps.LatLng(-33.8474, 151.2631));

var input = document.getElementById('searchTextField');

var searchBox = new google.maps.places.SearchBox(input, {
  bounds: defaultBounds
});

Suchbereich für SearchBox ändern

Wenn Sie den Suchbereich für ein vorhandenes SearchBox ändern möchten, rufen Sie setBounds() für das SearchBox-Objekt auf und übergeben das entsprechende LatLngBounds-Objekt.

Beispiel ansehen

Informationen zu Orten abrufen

Wenn der Nutzer ein Element aus den Vervollständigungen auswählt, die an das Suchfeld angehängt sind, löst der Dienst ein places_changed-Ereignis aus. Sie können getPlaces() für das Objekt SearchBox aufrufen, um ein Array mit mehreren Vorhersagen abzurufen, von denen jede ein PlaceResult-Objekt ist.

Weitere Informationen zum Objekt PlaceResult findest du in der Dokumentation zu Ortsdetailergebnissen.

TypeScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon as string,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );

    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

JavaScript

// Listen for the event fired when the user selects a prediction and retrieve
// more details for that place.
searchBox.addListener("places_changed", () => {
  const places = searchBox.getPlaces();

  if (places.length == 0) {
    return;
  }

  // Clear out the old markers.
  markers.forEach((marker) => {
    marker.setMap(null);
  });
  markers = [];

  // For each place, get the icon, name and location.
  const bounds = new google.maps.LatLngBounds();

  places.forEach((place) => {
    if (!place.geometry || !place.geometry.location) {
      console.log("Returned place contains no geometry");
      return;
    }

    const icon = {
      url: place.icon,
      size: new google.maps.Size(71, 71),
      origin: new google.maps.Point(0, 0),
      anchor: new google.maps.Point(17, 34),
      scaledSize: new google.maps.Size(25, 25),
    };

    // Create a marker for each place.
    markers.push(
      new google.maps.Marker({
        map,
        icon,
        title: place.name,
        position: place.geometry.location,
      })
    );
    if (place.geometry.viewport) {
      // Only geocodes have viewport.
      bounds.union(place.geometry.viewport);
    } else {
      bounds.extend(place.geometry.location);
    }
  });
  map.fitBounds(bounds);
});

Beispiel ansehen

Informationen zum Anpassen der Darstellung von Widgets finden Sie unter Stile für Autocomplete und SearchBox festlegen.

Place Autocomplete-Dienstvorhersagen programmatisch abrufen

Mit der Klasse AutocompleteService können Sie Vorhersagen programmatisch abrufen. AutocompleteService fügt keine UI-Steuerelemente hinzu. Stattdessen wird ein Array von Vorhersageobjekten zurückgegeben, die jeweils den Text der Vorhersage, Referenzinformationen und Details dazu enthalten, wie das Ergebnis mit der Nutzereingabe übereinstimmt. Dies ist nützlich, wenn Sie mehr Kontrolle über die Benutzeroberfläche haben möchten, als die oben beschriebenen Autocomplete und SearchBox bieten.

AutocompleteService stellt die folgenden Methoden bereit:

  • getPlacePredictions() gibt Ortsvorhersagen zurück. Hinweis: Ein Ort kann eine Einrichtung, ein geografischer Standort oder ein auffälliger POI sein, wie in der Places API definiert.
  • getQueryPredictions() gibt eine erweiterte Liste mit Vervollständigungen zurück, die Orte (wie in der Places API definiert) und vorgeschlagene Suchbegriffe enthalten kann. Wenn der Nutzer beispielsweise „pizza in berlin“ eingibt, kann die Auswahlliste den Text „pizza in berlin“ und die Namen verschiedener Pizzerien enthalten.

Beide oben genannten Methoden geben ein Array von Vorhersageobjekten in der folgenden Form zurück:

  • description ist die übereinstimmende Vervollständigung.
  • distance_meters ist die Entfernung in Metern vom Ort zum angegebenen AutocompletionRequest.origin.
  • matched_substrings enthält eine Reihe von Teilstrings in der Beschreibung, die mit Elementen in der Nutzereingabe übereinstimmen. Dies ist nützlich, um diese Teilstrings in Ihrer Anwendung hervorzuheben. In vielen Fällen wird die Abfrage als Teilstring des Beschreibungsfelds angezeigt.
    • length ist die Länge des Teilstrings.
    • offset ist das Zeichen-Offset, gemessen ab dem Beginn des Beschreibungsstrings, an dem der übereinstimmende Teilstring angezeigt wird.
  • place_id ist eine Textkennung, die einen Ort eindeutig bezeichnet. Übergeben Sie diese ID im Feld placeId einer Place Details-Anfrage, um Informationen zum Ort abzurufen. Weitere Informationen zum Verweisen auf einen Ort mit einer Orts-ID
  • terms ist ein Array, das Elemente der Abfrage enthält. Normalerweise stellt jedes Element für einen Ort einen Teil der Adresse dar.
    • offset ist das Zeichen-Offset, gemessen ab dem Beginn des Beschreibungsstrings, an dem der übereinstimmende Teilstring angezeigt wird.
    • value ist der passende Begriff.

Im folgenden Beispiel wird eine Anfrage zur Abfragevorhersage für die Wortgruppe & Pizza in der Nähe ausgeführt und das Ergebnis in einer Liste angezeigt.

TypeScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService(): void {
  const displaySuggestions = function (
    predictions: google.maps.places.QueryAutocompletePrediction[] | null,
    status: google.maps.places.PlacesServiceStatus
  ) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      (document.getElementById("results") as HTMLUListElement).appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

declare global {
  interface Window {
    initService: () => void;
  }
}
window.initService = initService;

JavaScript

// This example retrieves autocomplete predictions programmatically from the
// autocomplete service, and displays them as an HTML list.
// This example requires the Places library. Include the libraries=places
// parameter when you first load the API. For example:
// <script src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places">
function initService() {
  const displaySuggestions = function (predictions, status) {
    if (status != google.maps.places.PlacesServiceStatus.OK || !predictions) {
      alert(status);
      return;
    }

    predictions.forEach((prediction) => {
      const li = document.createElement("li");

      li.appendChild(document.createTextNode(prediction.description));
      document.getElementById("results").appendChild(li);
    });
  };

  const service = new google.maps.places.AutocompleteService();

  service.getQueryPredictions({ input: "pizza near Syd" }, displaySuggestions);
}

window.initService = initService;

CSS

HTML

<html>
  <head>
    <title>Retrieving Autocomplete 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>
    <p>Query suggestions for 'pizza near Syd':</p>
    <ul id="results"></ul>
    <!-- Replace Powered By Google image src with self hosted image. https://developers.google.com/maps/documentation/places/web-service/policies#other_attribution_requirements -->
    <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 callback 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
     with https://www.npmjs.com/package/@googlemaps/js-api-loader.
    -->
    <script
      src="https://maps.googleapis.com/maps/api/js?key=AIzaSyB41DRUbKWJHPxaFjMAwdrzWzbVKartNGg&callback=initService&libraries=places&v=weekly"
      defer
    ></script>
  </body>
</html>

Beispiel ausprobieren

Beispiel ansehen

Sitzungstokens

In AutocompleteService.getPlacePredictions() werden Sitzungstokens verwendet, um Anfragen zur automatischen Vervollständigung zu Abrechnungszwecken zu gruppieren. Sitzungstokens gruppieren die Abfrage- und Auswahlphasen einer automatischen Vervollständigung der Suche zu Abrechnungszwecken in eine separate Sitzung. Die Sitzung beginnt, wenn der Nutzer mit der Eingabe einer Abfrage beginnt, und endet, wenn er einen Ort auswählt. Jede Sitzung kann mehrere Abfragen enthalten, gefolgt von einer Ortsauswahl. Sobald eine Sitzung beendet ist, ist das Token nicht mehr gültig. Ihre Anwendung muss für jede Sitzung ein neues Token generieren. Wir empfehlen die Verwendung von Sitzungstokens für alle automatisch vervollständigten Sitzungen. Wenn der Parameter sessionToken weggelassen wird oder Sie ein Sitzungstoken wiederverwenden, wird die Sitzung so berechnet, als wäre kein Sitzungstoken angegeben worden. Jede Anfrage wird separat abgerechnet.

Sie können dasselbe Sitzungstoken verwenden, um eine einzelne Place Details-Anfrage an dem Ort zu senden, die sich aus einem Aufruf von AutocompleteService.getPlacePredictions() ergibt. In diesem Fall wird die Autocomplete-Anfrage mit der Place Details-Anfrage kombiniert und der Aufruf als reguläre „Place Details“-Anfrage berechnet. Für die Anfrage zur automatischen Vervollständigung fallen keine Kosten an.

Achten Sie darauf, für jede neue Sitzung ein eindeutiges Sitzungstoken zu übergeben. Wenn Sie dasselbe Token für mehr als eine Autocomplete-Sitzung verwenden, werden diese Autocomplete-Sitzungen ungültig. Alle Autocomplete-Anfragen in den ungültigen Sitzungen werden einzeln mithilfe der SKU „Autocomplete Per Request“ abgerechnet. Weitere Informationen zu Sitzungstokens

Das folgende Beispiel zeigt, wie ein Sitzungstoken erstellt und dann in einem AutocompleteService übergeben wird (der Funktion wurde der Kürze halber die Funktion displaySuggestions() weggelassen):

// Create a new session token.
var sessionToken = new google.maps.places.AutocompleteSessionToken();

// Pass the token to the autocomplete service.
var autocompleteService = new google.maps.places.AutocompleteService();
autocompleteService.getPlacePredictions({
  input: 'pizza near Syd',
  sessionToken: sessionToken
},
displaySuggestions);

Achten Sie darauf, für jede neue Sitzung ein eindeutiges Sitzungstoken zu übergeben. Wenn Sie dasselbe Token für mehr als eine Sitzung verwenden, wird jede Anfrage einzeln abgerechnet.

Weitere Informationen zu Sitzungstokens

Stile für Autocomplete und SearchBox festlegen

Die von Autocomplete und SearchBox bereitgestellten UI-Elemente werden standardmäßig so gestaltet, dass sie in eine Google-Karte aufgenommen werden. Du kannst das Design an deine Website anpassen. Die folgenden CSS-Klassen sind verfügbar. Alle unten aufgeführten Klassen gelten für die Widgets Autocomplete und SearchBox.

Grafische Darstellung der CSS-Klassen für die Autocomplete- und SearchBox-Widgets
CSS-Klassen für die Autocomplete- und SearchBox-Widgets
CSS-Klasse Beschreibung
pac-container Das visuelle Element, das die Liste der Vorhersagen enthält, die vom Place Autocomplete-Dienst zurückgegeben wurden. Diese Liste wird als Drop-down-Liste unter dem Widget Autocomplete oder SearchBox angezeigt.
pac-icon Das Symbol, das links neben jedem Element in der Liste der Vorhersagen angezeigt wird.
pac-item Ein Element in der Liste der Vorhersagen, die vom Widget Autocomplete oder SearchBox bereitgestellt wird.
pac-item:hover Das Element, das angezeigt wird, wenn der Benutzer mit dem Mauszeiger darauf zeigt.
pac-item-selected Das Element, das angezeigt wird, wenn der Benutzer es über die Tastatur auswählt. Hinweis: Die ausgewählten Elemente sind Mitglied dieser Klasse und der Klasse pac-item.
pac-item-query Ein Span innerhalb eines pac-item-Elements, das der Hauptteil der Vorhersage ist. Bei geografischen Standorten enthält dies einen Ortsnamen, z. B. 'Sydney' oder einen Straßennamen und eine Hausnummer, z. B. & Street King Street'. Für textbasierte Suchanfragen wie „pizza in new york“ wird der vollständige Text der Suchanfrage angezeigt. Standardmäßig ist pac-item-query schwarz. Wenn zusätzlicher Text in pac-item vorhanden ist, befindet er sich außerhalb von pac-item-query und übernimmt den Stil von pac-item. Standardmäßig wird das Element grau dargestellt. Der zusätzliche Text ist normalerweise eine Adresse.
pac-matched Der Teil der zurückgegebenen Vorhersage, der mit der Eingabe des Benutzers übereinstimmt. Standardmäßig wird dieser übereinstimmende Text fett formatiert. Der übereinstimmende Text kann sich innerhalb von pac-item befinden. Er ist nicht unbedingt Teil von pac-item-query und kann teilweise in pac-item-query sowie teilweise im verbleibenden Text in pac-item enthalten sein.

Place Autocomplete-Optimierung

In diesem Abschnitt werden Best Practices beschrieben, mit denen Sie den Place Autocomplete-Dienst optimal nutzen können.

Einige allgemeine Richtlinien:

  • Am schnellsten lässt sich eine funktionierende Benutzeroberfläche mit dem Widget „Autocomplete“ der Maps JavaScript API, dem Widget „Autocomplete“ des Places SDK for Android oder dem Widget „Autocomplete UI“ für das iOS SDK für iOS entwickeln.
  • Machen Sie sich von Anfang an mit den wichtigsten Datenfeldern von Place Autocomplete vertraut.
  • Die Felder zur Standortgewichtung und Standortbeschränkung sind optional, können aber erhebliche Auswirkungen auf die Leistung der automatischen Vervollständigung haben.
  • Verwenden Sie die Fehlerbehandlung, um sicherzustellen, dass sich die Fehlertoleranz der Anwendung beeinträchtigt, wenn die API einen Fehler zurückgibt.
  • Achte darauf, dass deine App auch dann verarbeitet wird, wenn keine Auswahl getroffen wird und Nutzern die Möglichkeit geboten wird, fortzufahren.

Best Practices für die Kostenoptimierung

Grundlegende Kostenoptimierung

Wenn Sie die Kosten für die Nutzung des Place Autocomplete-Dienstes optimieren möchten, verwenden Sie Feldmasken in den Place Details- und Place Autocomplete-Widgets, damit nur die erforderlichen Ortsdatenfelder zurückgegeben werden.

Erweiterte Kostenoptimierung

Ziehen Sie die programmatische Implementierung von Place Autocomplete in Betracht, um auf Preise pro Anfrage zuzugreifen und Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details anzufordern. Die Preise pro Anfrage in Kombination mit der Geocoding API sind kostengünstiger als Preise pro Sitzung (sitzungsbasiert), wenn die beiden folgenden Bedingungen erfüllt sind:

  • Wenn Sie nur den Breiten-/Längengrad oder die Adresse des ausgewählten Orts benötigen, liefert die Geocoding API diese Informationen für einen „Place Details“-Aufruf.
  • Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich vier Suchanfragen auswählen, sind die Preise pro Anfrage möglicherweise kosteneffizienter als die Preise pro Sitzung.
Wenn Sie Hilfe bei der Auswahl der Place Autocomplete-Implementierung benötigen, wählen Sie den Tab aus, der Ihrer Antwort auf die folgende Frage entspricht.

Sind für Ihre Anwendung andere Informationen als die Adresse und der Breiten-/Längengrad der ausgewählten Vervollständigung erforderlich?

Ja, weitere Details erforderlich

Verwenden Sie die sitzungsbasierte Place Autocomplete-Funktion mit Place Details-Anfragen.
Da für Ihre Anwendung Ortsdetails wie der Name des Orts, der Geschäftsstatus oder die Öffnungszeiten erforderlich sind, sollte bei der Implementierung von Place Autocomplete ein Sitzungstoken (programmatisch oder in die Widgets JavaScript, Android oder iOS) integriert sein.Die Gesamtkosten betragen 0,017 $pro Sitzung und die anwendbaren Places-Daten-SKUs, je nachdem, welche Ortsdatenfelder angefordert werden.

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in die Widgets
JavaScript, Android oder iOS integriert. Dies umfasst sowohl die Place Autocomplete-Anfragen als auch die Place Details-Anfrage für die ausgewählte Vervollständigung. Gib unbedingt den Parameter fields an, damit nur die erforderlichen Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Ihre Place Autocomplete-Anfragen ein Sitzungstoken. Geben Sie die folgenden Parameter an, wenn Sie Place Details zur ausgewählten Vervollständigung anfordern:

  1. Die Place ID aus der Place Autocomplete-Antwort
  2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage verwendet wird
  3. Der Parameter fields, der die erforderlichen Ortsdatenfelder angibt

Nein, es sind nur Adresse und Standort erforderlich

Die Geocoding API kann für Ihre Anwendung eine kostengünstigere Option als die „Place Details“-Funktion sein, abhängig von der Leistung Ihrer Place Autocomplete-Nutzung. Die Effizienz der automatischen Vervollständigung von Anwendungen hängt davon ab, was Nutzer eingeben, wo sie verwendet werden und ob Best Practices für die Leistungsoptimierung implementiert wurden.

Um die folgende Frage zu beantworten, analysieren Sie, wie viele Zeichen ein Nutzer durchschnittlich eingibt, bevor Sie in Ihrer App eine Place Autocomplete-Vervollständigung auswählen.

Wählen Ihre Nutzer durchschnittlich vier oder weniger Anfragen für die automatische Vervollständigung von Orten aus?

Ja

Place Autocomplete programmatisch ohne Sitzungstoken implementieren und die Geocoding API für die ausgewählte Ortsvorhersage aufrufen.
Die Geocoding API liefert Adressen und Breiten-/Längenkoordinaten für 0,005 $pro Anfrage. Vier Place Autocomplete – Per Request-Anfragen kosten 0,01132 $. Die Gesamtkosten für vier Anfragen sowie ein Geocoding API-Aufruf für die ausgewählte Ortsvorhersage wären dann 0,01632 $. Dieser Wert liegt unter dem Preis für die automatische Vervollständigung von Sitzungen von 0,017 $pro Sitzung.1

Mithilfe von Best Practices zur Leistung können Sie Nutzern helfen, Vorhersagen zu treffen, die sie mit weniger Zeichen erfüllen.

Nein

Verwenden Sie die sitzungsbasierte Place Autocomplete-Funktion mit Place Details-Anfragen.
Da die durchschnittliche Anzahl von Anfragen, die Sie erwarten, bevor ein Nutzer eine Place Autocomplete-Vorhersage auswählt, die Kosten pro Sitzung übersteigt, sollte Ihre Implementierung von Place Autocomplete für die Place Autocomplete-Anfragen und die zugehörige Place Details-Anfrage jeweils ein Sitzungstoken von insgesamt 0,017 $pro Sitzung verwenden.1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in die Widgets JavaScript, Android oder iOS integriert. Dies umfasst sowohl die Place Autocomplete-Anfragen als auch die Place Details-Anfrage für die ausgewählte Vervollständigung. Geben Sie unbedingt den Parameter fields an, damit nur Basisdaten-Felder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Ihre Place Autocomplete-Anfragen ein Sitzungstoken. Geben Sie die folgenden Parameter an, wenn Sie Place Details zur ausgewählten Vervollständigung anfordern:

  1. Die Place ID aus der Place Autocomplete-Antwort
  2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage verwendet wird
  3. Der Parameter fields, der Basisdaten-Felder wie Adresse und Geometrie angibt

Verzögern Sie Place Autocomplete-Anfragen.
Sie können beispielsweise eine Place Autocomplete-Anfrage verzögern, bis der Nutzer die ersten drei oder vier Zeichen eingegeben hat, sodass Ihre App weniger Anfragen stellt. Wenn beispielsweise Place Autocomplete-Anfragen für jedes Zeichen erfolgen, nachdem der Nutzer das dritte Zeichen eingegeben hat, würden die Gesamtkosten pro Nutzer, der sieben Zeichen eingibt und für die Sie eine Geocoding API-Anfrage stellen, 0,01632 $betragen (4 x 0,00283 $ für die automatische Vervollständigung pro Anfrage + 0,005 $für Geocoding).1

Wenn Ihre durchschnittliche programmatische Anfrage bei Anfragen unter drei liegen kann, folgen Sie der Anleitung für die leistungsstarke Place Autocomplete-Funktion mit der Geocoding API. Beachten Sie, dass die Verzögerung von Anfragen vom Nutzer, der möglicherweise mit jedem neuen Tastenanschlag Vorhersagen erwartet, als Latenz wahrgenommen wird.

Mithilfe von Best Practices zur Leistung können Sie Nutzern helfen, die Vorhersage zu erhalten, nach der sie suchen.


  1. Die hier aufgeführten Kosten sind in US-Dollar angegeben. Die vollständigen Preise finden Sie auf der Seite Google Maps Platform – Abrechnung.

Best Practices für die Leistung

In den folgenden Richtlinien wird beschrieben, wie die Leistung von Place Autocomplete optimiert werden kann:

  • Fügen Sie Ihrer Place Autocomplete-Implementierung länderspezifische Einschränkungen, die Standortverzerrung und (bei programmatischen Implementierungen) die Spracheinstellung hinzu. Die Spracheinstellung ist bei Widgets nicht erforderlich, da sie Spracheinstellungen vom Browser oder Mobilgerät des Nutzers auswählen.
  • Wenn die Place Autocomplete-Funktion von einer Karte begleitet wird, können Sie den Standort anhand des Darstellungsbereichs der Karte anpassen.
  • Wenn ein Nutzer keine der automatischen Vervollständigungen auswählt, denn in der Regel handelt es sich dabei nicht um die gewünschte Ergebnisadresse. In diesem Fall kannst du die ursprüngliche Nutzereingabe wiederverwenden, um relevantere Ergebnisse zu erhalten:
    • Wenn der Nutzer nur Adressinformationen eingeben soll, verwenden Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal.
    • Wenn du davon ausgehst, dass der Nutzer Abfragen für einen bestimmten Ort nach Name oder Adresse eingibt, verwende eine Find Place-Anfrage. Wenn Ergebnisse nur in einer bestimmten Region erwartet werden, verwenden Sie die Standortgewichtung.
    Wenn Sie zur Geocoding API zurückkehren möchten, sind weitere Szenarien möglich:
    • Nutzer, die untergeordnete Adressen in anderen Ländern als Australien, Neuseeland oder Kanada eingeben. Beispielsweise wird die US-Adresse 123 Bowdoin St #456, Boston MA, USA nicht von der automatischen Vervollständigung unterstützt. (Die automatische Vervollständigung unterstützt nur lokale Adressen in Australien, Neuseeland und Kanada. Unterstützte Adressformate in diesen drei Ländern sind &9
    • Nutzer, die Adressen mit Präfixen für Straßensegmente wie „23-30 29th St, Queens & New York City“ oder „47–380 Kamphameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii eingeben

Nutzungsbeschränkungen und Richtlinien

Kontingente

Informationen zu Kontingenten und Preisen finden Sie in der Dokumentation zur Nutzung und Abrechnung der Places API.

Richtlinien

Die Nutzung der Places Library, Maps JavaScript API muss den Richtlinien für die Places API entsprechen.

Aus unseren Nutzungsbedingungen

Erforderliche
Logos und Quellenangaben anzeigen

Respektieren Sie die Urheberrechte und Quellenangaben von Google. Achte darauf, dass das Logo und der Urheberrechtshinweis sichtbar sind und das Logo von Google angezeigt wird, wenn du Daten ohne Karte verwendest.

Weitere Informationen