Place Autocomplete (alte Version)

Entwickler im Europäischen Wirtschaftsraum (EWR)

Place Autocomplete (Legacy) ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Ortsvorschläge zurückgibt. Die Anfrage enthält einen Textsuchstring und optionale geografische Grenzen. Der Dienst kann verwendet werden, um die automatische Vervollständigung für textbasierte geografische Suchanfragen zu ermöglichen. Dazu werden Orte wie Unternehmen, Adressen und POIs zurückgegeben, während ein Nutzer Text eingibt.

Place Autocomplete-Anfragen (Legacy)

„Place Autocomplete“ (Legacy) ist Teil der Places API und verwendet einen API-Schlüssel und Kontingente der Places API.

Place Autocomplete (Legacy) findet Übereinstimmungen mit vollständigen Wörtern und Teilstrings, sodass sich Ortsnamen, Adressen und Plus Codes zuordnen lassen. Anwendungen können Abfragen senden, während der Nutzer tippt, und schon bei der Eingabe Ortsvorschläge ausgeben.

Plus Codes müssen richtig formatiert sein. Das bedeutet, dass Sie das Pluszeichen in der URL als %2B und Leerzeichen als %20 darstellen müssen.

  • Global Code besteht aus einem vierstelligen Vorwahl-Code und einem mindestens sechsstelligen lokalen Code. Der globale URL-Escape-Code 849VCWC8+R9 ist beispielsweise 849VCWC8%2BR9.
  • Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort. Der URL-escapte zusammengesetzte Code CWC8+R9 Mountain View, CA, USA ist beispielsweise CWC8%2BR9%20Mountain%20View%20CA%20USA.

Die zurückgegebenen Vorhersagen sind so konzipiert, dass sie dem Nutzer angezeigt werden, um ihm bei der Auswahl des gewünschten Orts zu helfen. Sie können eine Place Details (Legacy)-Anfrage senden, um weitere Informationen zu den zurückgegebenen Orten zu erhalten.

Eine „Place Autocomplete“-Anfrage (Legacy) ist eine HTTP-URL mit folgendem Format:

https://maps.googleapis.com/maps/api/place/autocomplete/output?parameters

Dabei kann output einer der folgenden Werte sein:

  • json (empfohlen) gibt die Ausgabe in JavaScript Object Notation (JSON) an.
  • xml gibt die Ausgabe als XML an.

Bestimmte Parameter sind erforderlich, um eine „Place Autocomplete (Legacy)“-Anfrage zu starten. Wie in URLs üblich, werden alle Parameter mit dem Und-Zeichen (&) getrennt. Die Liste der Parameter und ihrer möglichen Werte ist unten aufgeführt.

Erforderliche Parameter

  • Eingabe

    Der Textstring, nach dem gesucht werden soll. Über den Place Autocomplete-Dienst werden mögliche Übereinstimmungen basierend auf dem String zurückgegeben, die nach erkannter Relevanz sortiert werden.

Optionale Parameter

  • Komponenten

    Eine Gruppierung von Orten, auf die Sie Ihre Ergebnisse beschränken möchten. Mit Komponenten können Sie nach bis zu fünf Ländern filtern. Länder müssen als Ländercode mit 2 Zeichen gemäß ISO 3166-1 Alpha-2 übergeben werden. Beispiel: components=country:fr würde die Ergebnisse auf Orte in Frankreich beschränken. Mehrere Länder müssen als mehrere country:XX-Filter übergeben werden, wobei der senkrechte Strich | als Trennzeichen dient. Beispiel: components=country:us|country:pr|country:vi|country:gu|country:mp würde Ihre Ergebnisse auf Orte in den USA und den nicht eingegliederten organisierten Gebieten beschränken.

    Hinweis:Wenn unerwartete Ergebnisse mit einem Ländercode ausgegeben werden, sollten Sie prüfen, ob Sie einen Code verwenden, der die gewünschten Länder, Außengebiete und besonderen Gebiete von geografischem Interesse umfasst. Informationen zu den Codes finden Sie in der ISO 3166-Ländercodeliste auf Wikipedia oder auf der ISO Online Browsing Platform.

  • Sprache

    Die Sprache, in der Ergebnisse zurückgegeben werden sollen.

    • Hier finden Sie eine Liste der unterstützten Sprachen. Die unterstützten Sprachen werden regelmäßig von Google aktualisiert, sodass diese Liste unter Umständen nicht vollständig ist.
    • Wenn language nicht angegeben ist, versucht die API, die im Header Accept-Language angegebene bevorzugte Sprache zu verwenden.
    • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Adressen in der Landessprache zurückgegeben, die bei Bedarf in eine für den Nutzer lesbare Schrift transliteriert werden. Dabei wird die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
    • Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, wird die nächstgelegene Übereinstimmung verwendet.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die von der API zurückgegebenen Ergebnisse und die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. die Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sein können, in einer anderen jedoch nicht. Beispiel: utca und tér sind Synonyme für „Straße“ auf Ungarisch.

  • Standort

    Der Punkt, um den herum Ortsinformationen abgerufen werden sollen. Dies muss als latitude,longitude angegeben werden. Der Parameter radius muss auch angegeben werden, wenn ein Standort festgelegt wird. Wenn radius nicht angegeben ist, wird der Parameter location ignoriert.

    Wenn Sie die Text Search API verwenden, wird der Parameter „location“ möglicherweise überschrieben, wenn die „query“ einen expliziten Ort wie „Markt in Barcelona“ enthält.

  • locationbias

    Ergebnisse in einem bestimmten Gebiet bevorzugen, indem Sie entweder einen Radius plus Breiten-/Längengrad oder zwei Breiten-/Längengradpaare angeben, die die Punkte eines Rechtecks darstellen. Wenn dieser Parameter nicht angegeben ist, verwendet die API standardmäßig die IP-Adressgewichtung.

    • IP-Bias: Weist die API an, IP-Adressen-Bias zu verwenden. Übergeben Sie den String ipbias (für diese Option sind keine zusätzlichen Parameter erforderlich).
    • Kreisförmig: Ein String, der den Radius in Metern sowie den Breiten- und Längengrad in Dezimalgrad angibt. Verwenden Sie das folgende Format: circle:radius@lat,lng.
    • Rechteckig: Ein String, der zwei Breiten-/Längenkoordinatenpaare in Dezimalgrad angibt, die die Südwest- und Nordostecke eines Rechtecks darstellen. Verwenden Sie das folgende Format:rectangle:south,west|north,east. Beachten Sie, dass Ost-/Westwerte auf den Bereich -180, 180 und Nord-/Südwerte auf den Bereich -90, 90 beschränkt sind.

  • locationrestriction

    Sie können die Ergebnisse auf einen bestimmten Bereich beschränken, indem Sie entweder einen Radius plus Breiten-/Längenkoordinaten oder zwei Paare aus Breiten-/Längenkoordinaten angeben, die die Punkte eines Rechtecks darstellen.

    • Kreisförmig: Ein String, der den Radius in Metern sowie den Breiten- und Längengrad in Dezimalgrad angibt. Verwenden Sie das folgende Format: circle:radius@lat,lng.
    • Rechteckig: Ein String, der zwei Paare aus Breiten-/Längenkoordinaten in Dezimalgrad angibt, die die südwestlichen und nordöstlichen Punkte eines Rechtecks darstellen. Verwenden Sie das folgende Format:rectangle:south,west|north,east. Hinweis: Ost-/Westwerte werden auf den Bereich -180 bis 180 und Nord-/Südwerte auf den Bereich -90 bis 90 begrenzt.

  • kompensiert

    Die Position des letzten Zeichens im Eingabeterm, das vom Dienst zum Abgleichen von Vorhersagen verwendet wird. Wenn die Eingabe beispielsweise Google und der Offset 3 ist, wird der Dienst mit Goo abgeglichen. Die durch den Offset bestimmte Zeichenfolge wird nur mit dem ersten Wort im Eingabeterm abgeglichen. Wenn der Eingabebegriff beispielsweise Google abc und der Offset 3 ist, versucht der Dienst, eine Übereinstimmung mit Goo abc zu finden. Wenn kein Offset angegeben wird, wird der gesamte Zeitraum verwendet. Der Offset sollte in der Regel auf die Position des Textcursors festgelegt werden.

  • origin

    Der Ausgangspunkt, von dem aus die Luftlinie zum Ziel berechnet werden soll (wird als distance_meters zurückgegeben). Wenn dieser Wert weggelassen wird, wird die Luftlinie nicht zurückgegeben. Muss als latitude,longitude angegeben werden.

  • Umkreis

    Definiert die Entfernung (in Metern), innerhalb derer Ortsangaben zurückgegeben werden sollen. Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Kreises gewichten. Dadurch wird der Places-Dienst angewiesen, vorzugsweise Ergebnisse für Orte anzuzeigen, die sich innerhalb dieses Kreises befinden. Ergebnisse außerhalb des definierten Bereichs können aber trotzdem angezeigt werden.

    Der Radius wird automatisch auf einen Höchstwert begrenzt, der vom Suchtyp und anderen Parametern abhängt.

    • Autovervollständigung: 50.000 Meter
    • Nearby Search:
      • mit keyword oder name: 50.000 Meter
      • ohne keyword oder name
        • Bis zu 50.000 Meter, dynamisch angepasst basierend auf der Gebietsdichte, unabhängig vom Parameter rankby.
        • Wenn Sie rankby=distance verwenden, wird der Radiusparameter nicht akzeptiert und es wird ein INVALID_REQUEST zurückgegeben.
    • Query Autocomplete: 50.000 Meter
    • Textsuche: 50.000 Meter

  • Region

    Der Regionscode, angegeben als zweistelliger Ländercode der Top-Level-Domain (ccTLD). Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs ist beispielsweise „uk“ (.co.uk), der ISO 3166-1-Code „gb“ (technisch für das Land „Vereinigtes Königreich Großbritannien und Nordirland“).

  • sessiontoken

    Ein zufälliger String, der eine Sitzung zur automatischen Vervollständigung zu Abrechnungszwecken identifiziert.

    Die Sitzung wird gestartet, wenn der Nutzer mit der Eingabe beginnt, und endet, wenn er einen Ort auswählt und ein Aufruf an „Place Details“ erfolgt. Jede Sitzung kann mehrere Abfragen und eine Ortsauswahl umfassen. Die API-Schlüssel, die für die einzelnen Anfragen innerhalb einer Sitzung verwendet werden, müssen zum selben Google Cloud Console-Projekt gehören. Sobald eine Sitzung beendet wird, ist das Token nicht mehr gültig. Ihre Anwendung muss für jede Sitzung ein neues Token generieren. Wenn Sie den sessiontoken-Parameter weglassen oder ein Sitzungstoken wiederverwenden, wird die Sitzung so in Rechnung gestellt, als wäre kein Sitzungstoken bereitgestellt worden. Jede Anfrage wird separat abgerechnet.

    Wir empfehlen folgende Richtlinien:

    • Verwenden Sie Sitzungstokens für alle Sitzungen, bei denen eine automatische Vervollständigung erfolgt.
    • Generieren Sie für jede Sitzung ein neues Token. Ein UUID der Version 4 wird empfohlen.
    • Achten Sie darauf, dass die API-Schlüssel, die für alle „Place Autocomplete“- und „Place Details“-Anfragen innerhalb einer Sitzung verwendet werden, zum selben Cloud Console-Projekt gehören.
    • Für jede neue Sitzung muss ein eindeutiges Sitzungstoken weitergegeben werden. Wenn Sie dasselbe Token für mehr als eine Sitzung verwenden, wird jede Anfrage separat in Rechnung gestellt.

  • strictbounds

    Gibt nur die Orte zurück, die sich genau in der mit location und radius angegebenen Region befinden. Dies ist eine Einschränkung und keine Verzerrung. Das bedeutet, dass Ergebnisse außerhalb dieser Region nicht zurückgegeben werden, selbst wenn sie mit der Nutzereingabe übereinstimmen.

  • Typen

    Sie können die Ergebnisse einer Place Autocomplete-Anfrage auf einen bestimmten Typ beschränken, indem Sie den Parameter types übergeben. Mit diesem Parameter wird ein Typ oder werden mehrere Typen angegeben, wie unter Ortstypen aufgeführt. Wurde nichts angegeben, werden alle Typen zurückgegeben.

    Ein Ort kann nur einen einzigen primären Typ aus den in Tabelle 1 oder Tabelle 2 aufgeführten Typen haben. Ein Hotel, in dem Speisen serviert werden, kann beispielsweise nur mit types=lodging und nicht mit types=restaurant zurückgegeben werden.

    Für den Wert des Parameters types können Sie Folgendes angeben:

    • Bis zu fünf Werte aus Tabelle 1 oder Tabelle 2. Trennen Sie mehrere Werte durch einen vertikalen Strich |. Beispiel:

      types=book_store|cafe

    • Einen beliebigen unterstützten Filter aus Tabelle 3. Sie können keine Typensammlungen mischen.

    Die Anfrage wird mit dem Fehler INVALID_REQUEST abgelehnt, wenn:

    • Es wurden mehr als fünf Typen angegeben.
    • Es sind unbekannte Typen vorhanden.
    • Sie haben sowohl Typen aus Tabelle 1 oder Tabelle 2 als auch Filter aus Tabelle 3 angegeben.

Beispiele für Place Autocomplete (Legacy)

Eine Anfrage für Unternehmen, die den String „Amoeba“ in einem Gebiet mit dem Zentrum in San Francisco, Kalifornien, enthalten:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696
      &radius=500
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&key=YOUR_API_KEY'

Dieselbe Anfrage, beschränkt auf Ergebnisse im Umkreis von 500 Metern um Ashbury St & Haight St, San Francisco:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=amoeba
      &types=establishment
      &location=37.76999%2C-122.44696&radius=500
      &strictbounds=true
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=amoeba&types=establishment&location=37.76999%2C-122.44696&radius=500&strictbounds=true&key=YOUR_API_KEY'

Eine Anfrage für Adressen, die "Vict" enthalten, mit Ergebnissen in Französisch:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=geocode
      &language=fr
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=geocode&language=fr&key=YOUR_API_KEY'

Eine Anfrage für Städte, die „Vict“ enthalten, mit Ergebnissen in brasilianischem Portugiesisch:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Vict
      &types=(cities)
      &language=pt_BR&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Vict&types=(cities)&language=pt_BR&key=YOUR_API_KEY'

Den API-Schlüssel in diesen Beispielen müssen Sie durch Ihren eigenen Schlüssel ersetzen.

Place Autocomplete (Legacy)-Antwort

Place Autocomplete-Antworten (Legacy) werden in dem Format zurückgegeben, das durch das Flag output im URL-Pfad der Anfrage angegeben wird. Die folgenden Ergebnisse sind ein Hinweis darauf, was für eine Anfrage mit den folgenden Parametern zurückgegeben werden kann:

URL

https://maps.googleapis.com/maps/api/place/autocomplete/json
      ?input=Paris
      &types=geocode
      &key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/place/autocomplete/json?input=Paris&types=geocode&key=YOUR_API_KEY'

JSON

{
  "predictions":
    [
      {
        "description": "Paris, France",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "reference": "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "France",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "France" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TX, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "reference": "ChIJmysnFgZYSoYRSfPTL2YJuck",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TX, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TX" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, TN, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "reference": "ChIJ4zHP-Sije4gRBDEsVxunOWg",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "TN, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "TN" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
      {
        "description": "Paris, Brant, ON, Canada",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "reference": "ChIJsamfQbVtLIgR-X18G75Hyi0",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "Brant, ON, Canada",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "Brant" },
            { "offset": 14, "value": "ON" },
            { "offset": 18, "value": "Canada" },
          ],
        "types": ["neighborhood", "political", "geocode"],
      },
      {
        "description": "Paris, KY, USA",
        "matched_substrings": [{ "length": 5, "offset": 0 }],
        "place_id": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "reference": "ChIJsU7_xMfKQ4gReI89RJn0-RQ",
        "structured_formatting":
          {
            "main_text": "Paris",
            "main_text_matched_substrings": [{ "length": 5, "offset": 0 }],
            "secondary_text": "KY, USA",
          },
        "terms":
          [
            { "offset": 0, "value": "Paris" },
            { "offset": 7, "value": "KY" },
            { "offset": 11, "value": "USA" },
          ],
        "types": ["locality", "political", "geocode"],
      },
    ],
  "status": "OK",
}

XML

    
<?xml version="1.0" encoding="UTF-8"?>
<AutocompletionResponse>
 <status>OK</status>
 <prediction>
  <description>Paris, France</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>France</value>
   <offset>7</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>France</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TX, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJmysnFgZYSoYRSfPTL2YJuck</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJmysnFgZYSoYRSfPTL2YJuck</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TX, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, TN, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJ4zHP-Sije4gRBDEsVxunOWg</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TN</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJ4zHP-Sije4gRBDEsVxunOWg</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>TN, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, Brant, ON, Canada</description>
  <type>neighborhood</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsamfQbVtLIgR-X18G75Hyi0</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Brant</value>
   <offset>7</offset>
  </term>
  <term>
   <value>ON</value>
   <offset>14</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>18</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsamfQbVtLIgR-X18G75Hyi0</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>Brant, ON, Canada</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
 <prediction>
  <description>Paris, KY, USA</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <reference>ChIJsU7_xMfKQ4gReI89RJn0-RQ</reference>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>KY</value>
   <offset>7</offset>
  </term>
  <term>
   <value>USA</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
  <place_id>ChIJsU7_xMfKQ4gReI89RJn0-RQ</place_id>
  <structured_formatting>
   <description>Paris</description>
   <subdescription>KY, USA</subdescription>
   <description_matched_substring>
    <offset>0</offset>
    <length>5</length>
   </description_matched_substring>
  </structured_formatting>
 </prediction>
</AutocompletionResponse>

PlacesAutocompleteResponse

Feld Erforderlich Typ Beschreibung
required Array<PlaceAutocompletePrediction>

Enthält ein Array von Vervollständigungen.

Weitere Informationen finden Sie unter PlaceAutocompletePrediction.

required PlacesAutocompleteStatus

Enthält den Status der Anfrage und evtl. Debugging-Informationen, mit deren Hilfe Sie herausfinden können, warum die Anfrage zu Fehlern geführt hat.

Weitere Informationen finden Sie unter PlacesAutocompleteStatus.

optional String

Wenn der Dienst einen anderen Statuscode als OK< zurückgibt, kann im Antwortobjekt ein zusätzliches Feld error_message vorhanden sein. Dieses Feld enthält detailliertere Informationen zu den Gründen für den angegebenen Statuscode. Dieses Feld wird nicht immer zurückgegeben und sein Inhalt kann sich ändern.

optional Array<string>

Wenn der Dienst zusätzliche Informationen zur Anfragespezifikation zurückgibt, kann im Antwortobjekt ein zusätzliches info_messages-Feld vorhanden sein. Dieses Feld wird nur für erfolgreiche Anfragen zurückgegeben. Sie wird möglicherweise nicht immer zurückgegeben und ihr Inhalt kann sich ändern.

Besonders interessant sind die place_id-Elemente, mit denen Sie über eine separate Abfrage genauere Details zum Ort anfordern können. Weitere Informationen finden Sie unter Place Details (Legacy)-Anfragen.

Eine XML-Antwort besteht aus einem einzelnen <AutocompletionResponse>-Element mit zwei Arten von untergeordneten Elementen:

  • Ein einzelnes <status>-Element enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unten unter Statuscodes.
  • Null oder mehr <prediction>-Elemente, die jeweils Informationen zu einem einzelnen Ort enthalten. Informationen zu diesen Ergebnissen finden Sie unter Place Autocomplete (Legacy)-Ergebnisse. Die Places API gibt bis zu 5 Ergebnisse zurück.

Wir empfehlen, json als bevorzugtes Ausgabeflag zu verwenden, es sei denn, Ihre Anwendung erfordert aus irgendeinem Grund xml. Die Verarbeitung von XML-Bäumen erfordert eine gewisse Sorgfalt, damit Sie auf die richtigen Knoten und Elemente verweisen. Weitere Informationen zum Verarbeiten von XML finden Sie unter XML mit XPath verarbeiten.

PlacesAutocompleteStatus

Vom Dienst zurückgegebene Statuscodes.

  • OK: Die API-Anfrage war erfolgreich.
  • ZERO_RESULTS gibt an, dass die Suche erfolgreich war, aber keine Ergebnisse zurückgegeben wurden. Dieser Status kann ausgegeben werden, wenn der Suche Grenzen an einem abgelegenen Ort übergeben wurden.
  • INVALID_REQUEST: Die API-Anfrage war fehlerhaft, in der Regel aufgrund des fehlenden Parameters input.
  • OVER_QUERY_LIMIT mit einer der folgenden Angaben:
    • Sie haben die Limits für die maximal zulässige Anzahl von Abfragen pro Sekunde überschritten.
    • Die Abrechnung wurde für Ihr Konto nicht aktiviert.
    • Das monatliche Guthaben von 200 $ oder das von Ihnen festgelegte Nutzungslimit wurde überschritten.
    • Die angegebene Zahlungsmethode ist nicht mehr gültig. Das kann z. B. bei einer abgelaufenen Kreditkarte der Fall sein.
    Weitere Informationen zur Behebung dieses Fehlers finden Sie in den FAQs zu Maps.
  • REQUEST_DENIED gibt an, dass Ihre Anfrage abgelehnt wurde, in der Regel aus folgenden Gründen:
    • In der Anfrage fehlt ein API-Schlüssel.
    • Der Parameter key ist ungültig.
  • UNKNOWN_ERROR: Ein unbekannter Fehler ist aufgetreten.

Wenn der Places-Dienst JSON-Ergebnisse aus einer Suche zurückgibt, werden diese in einem predictions-Array platziert. Auch wenn der Dienst keine Ergebnisse zurückgibt (z. B. wenn location remote ist), wird trotzdem ein leeres predictions-Array zurückgegeben. XML-Antworten bestehen aus null oder mehr <prediction>-Elementen.

PlaceAutocompletePrediction

Feld Erforderlich Typ Beschreibung
erforderlich String

Enthält den menschenlesbaren Namen für das zurückgegebene Ergebnis. Bei establishment-Ergebnissen ist das in der Regel der Unternehmensname. Der Inhalt ist so zu lesen, wie er ist. Die formatierte Adresse darf nicht programmatisch geparst werden.

required Array<PlaceAutocompleteMatchedSubstring>

Eine Liste von Teilstrings, die die Position des eingegebenen Begriffs im Text des Vervollständigungsergebnisses beschreiben, sodass der Begriff bei Bedarf hervorgehoben werden kann.

Weitere Informationen finden Sie unter PlaceAutocompleteMatchedSubstring.

required PlaceAutocompleteStructuredFormat

Stellt vorformatierten Text bereit, der in den Ergebnissen der automatischen Vervollständigung angezeigt werden kann. Der Inhalt ist so zu lesen, wie er ist. Die formatierte Adresse darf nicht programmatisch geparst werden.

Weitere Informationen finden Sie unter PlaceAutocompleteStructuredFormat.

required Array<PlaceAutocompleteTerm>

Enthält ein Array mit Begriffen, die die einzelnen Abschnitte der zurückgegebenen Beschreibung identifizieren. Ein Abschnitt der Beschreibung wird in der Regel mit einem Komma beendet. Jeder Eintrag im Array hat ein Feld value mit dem Text des Begriffs und ein Feld offset, das die Startposition dieses Begriffs in der Beschreibung in Unicode-Zeichen angibt.

Weitere Informationen finden Sie unter PlaceAutocompleteTerm.

optional integer

Die Luftlinie in Metern vom Startpunkt. Dieses Feld wird nur für Anfragen zurückgegeben, die mit einem origin gestellt werden.

optional String

Eine ID in Textform, die einen Ort eindeutig bezeichnet. Übergeben Sie die Kennung im Feld „placeId“ einer Places API-Anfrage, um Informationen zum Ort abzurufen. Weitere Informationen finden Sie in der Übersicht zur Orts-ID.

optional String

Siehe „place_id“.
optional Array<string>

Enthält ein Array von Typen, die für diesen Ort gelten. Beispiel: [ "political", "locality" ] oder [ "establishment", "geocode", "beauty_salon" ]. Das Array kann mehrere Werte enthalten. Weitere Informationen zu Ortstypen

PlaceAutocompleteMatchedSubstring

Feld Erforderlich Typ Beschreibung
erforderlich Zahl

Länge des übereinstimmenden Teilstrings im Text des Vorhersageergebnisses.
required Zahl

Startposition des übereinstimmenden Teilstrings im Text des Vorhersageergebnisses.

PlaceAutocompleteStructuredFormat

Feld Erforderlich Typ Beschreibung

main_text

erforderlich String

Enthält den Haupttext einer Vorhersage, in der Regel den Namen des Orts.

main_text_matched_substrings

required Array<PlaceAutocompleteMatchedSubstring>

Enthält ein Array mit dem Wert offset und length. Sie beschreiben die Position des eingegebenen Begriffs im Text des Vorhersageergebnisses, sodass der Begriff bei Auswahl hervorgehoben werden kann.

Weitere Informationen finden Sie unter PlaceAutocompleteMatchedSubstring.

secondary_text

optional String

Enthält den sekundären Text einer Vorhersage, in der Regel den Standort des Orts.

secondary_text_matched_substrings

optional Array<PlaceAutocompleteMatchedSubstring>

Enthält ein Array mit dem Wert offset und length. Sie beschreiben die Position des eingegebenen Begriffs im Text des Vorhersageergebnisses, sodass der Begriff bei Auswahl hervorgehoben werden kann.

Weitere Informationen finden Sie unter PlaceAutocompleteMatchedSubstring.

PlaceAutocompleteTerm

Feld Erforderlich Typ Beschreibung
erforderlich Zahl

Definiert die Startposition dieses Begriffs in der Beschreibung, gemessen in Unicode-Zeichen.

required String

Der Text des Begriffs.

Place Autocomplete (Legacy) optimieren

Hier finden Sie Best Practices, damit Sie den Place Autocomplete-Dienst (Legacy) optimal nutzen können.

Allgemeine Richtlinien:

Best Practices für die Kostenoptimierung

Einfache Kostenoptimierung

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

Erweiterte Kostenoptimierung

Wenn Sie Place Autocomplete (Legacy) programmatisch implementieren, erhalten Sie Zugriff auf die SKU: Autocomplete – Per Request pricing und können Geocoding API-Ergebnisse für den ausgewählten Ort anstelle von Place Details (Legacy)-Ergebnissen anfordern. Wenn Sie die Kosten pro Anfrage mit der Geocoding API kombinieren, ist das kosteneffizienter als die Verwendung von Kosten pro Sitzung (sitzungsbasiert), sofern die beiden folgenden Bedingungen erfüllt werden:

  • Wenn Sie nur den Breiten- und Längengrad oder die Adresse des vom Nutzer ausgewählten Orts abrufen möchten, erhalten Sie entsprechende Informationen über die Geocoding API, für die weniger Kosten anfallen als bei einem Place Details-Aufruf (Legacy).
  • Wenn Nutzer eine automatische Vervollständigung bei durchschnittlich maximal 4 entsprechenden Place Autocomplete (Legacy)-Anfragen auswählen, ist der Preis pro Anfrage möglicherweise kosteneffizienter als der Preis pro Sitzung.
Wenn Sie Hilfe bei der Auswahl der Place Autocomplete (Legacy)-Implementierung benötigen, klicken Sie auf den Tab, der Ihrer Antwort auf die folgende Frage am ehesten entspricht.

Benötigt Ihre Anwendung weitere Informationen als Adresse und Breiten-/Längengrad des ausgewählten Vorschlags?

Ja, weitere Details sind erforderlich.

Nutzen Sie das sitzungsbasierte Place Autocomplete-Modell (Legacy) mit Place Details-Anfragen (Legacy).
Da für Ihre Anwendung „Place Details (Legacy)“ wie Ortsname, Unternehmensstatus oder Öffnungszeiten erforderlich sind, sollte für die Implementierung von „Place Autocomplete (Legacy)“ ein Sitzungstoken (programmatisch oder in die JavaScript-, Android- oder iOS-Widgets integriert) pro Sitzung sowie die entsprechenden Places Data-SKUs verwendet werden, je nachdem, welche Ortsdatenfelder Sie anfordern.1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android oder iOS integriert. Das umfasst sowohl Place Autocomplete-Anfragen (Legacy) als auch die Place Details-Anfrage (Legacy) für den ausgewählten Vorschlag. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Datenfelder für Place Autocomplete (Legacy) angefordert werden.

Programmatische Implementierung
Verwenden Sie für Place Autocomplete-Anfragen (Legacy) ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Details zum Ort (Legacy) für den ausgewählten Vorschlag anfordern:

  1. Die Orts-ID aus der Place Autocomplete-Antwort (Legacy)
  2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage (Legacy) verwendet wird
  3. Den fields-Parameter, mit dem die erforderlichen Datenfelder für Place Autocomplete (Legacy) angegeben werden

Nein, es sind nur Adresse und Standort erforderlich.

Wenn Sie Place Autocomplete (Legacy) in Ihrer Anwendung stark nutzen, kann es kostengünstiger sein, anstelle von Place Details (Legacy) die Geocoding API zu verwenden. Die Effizienz der Place Autocomplete-Funktion (Legacy) jeder Anwendung hängt davon ab, was die Nutzer eingeben, wo die Anwendung verwendet wird und ob die Best Practices zur Leistungsoptimierung implementiert wurden.

Um die folgende Frage beantworten zu können, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Place Autocomplete-Vorschlag (Legacy) auswählen.

Wählen Ihre Nutzer durchschnittlich bei 4 oder weniger Anfragen einen Place Autocomplete-Vorschlag (Legacy) aus?

Ja

Implementieren Sie Place Autocomplete (Legacy) programmatisch ohne Sitzungstokens und rufen Sie die Geocoding API für den ausgewählten Ortsvorschlag auf.
Über die Geocoding API erhalten Sie Adressen und Breiten-/Längenkoordinaten. Wenn 4 Autocomplete-Anfragen mit Preis pro Anfrage ausgeführt werden, fallen Kosten von 0,01132 $ an. Die Gesamtkosten der 4 Anfragen plus die Kosten für einen Geocoding API-Aufruf zum ausgewählten Ortsvorschlag betragen 0,01632 $, also weniger als der Preis pro Sitzung mit automatischer Vervollständigung von 0,017 $ pro Sitzung.1

Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vorschläge.

Nein

Verwenden Sie das sitzungsbasierte Place Autocomplete-Modell (alt) mit Place Details-Anfragen (alt).
Da die durchschnittliche Anzahl der Anfragen, die Sie voraussichtlich stellen, bevor ein Nutzer einen Place Autocomplete (Legacy)-Vorschlag auswählt, die Kosten für die Preisgestaltung pro Sitzung übersteigt, sollte für Ihre Implementierung von Place Autocomplete (Legacy) ein Sitzungstoken für die Place Autocomplete (Legacy)-Anfragen und die zugehörige Place Details (Legacy)-Anfrage verwendet werden pro Sitzung. 1

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android oder iOS integriert. Das umfasst sowohl Place Autocomplete-Anfragen (Legacy) als auch die Place Details-Anfrage (Legacy) für den ausgewählten Vorschlag. Der fields-Parameter muss festgelegt werden, damit nur die erforderlichen Felder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Place Autocomplete-Anfragen (Legacy) ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (Legacy) für den ausgewählten Vorschlag anfordern:

  1. Die Orts-ID aus der Place Autocomplete (Legacy)-Antwort
  2. Das Sitzungstoken, das in der Place Autocomplete-Anfrage (Legacy) verwendet wird
  3. Den fields-Parameter, mit dem grundlegende Datenfelder wie das Feld „Adresse“ oder „Geometrie“ angegeben werden

Place Autocomplete (Legacy)-Anfragen verzögern
Sie können Place Autocomplete (Legacy)-Anfragen verzögern, bis der Nutzer die ersten 3 oder 4 Zeichen eingegeben hat, damit weniger Anfragen über die Anwendung gestellt werden. Wenn Sie beispielsweise Place Autocomplete-Anfragen (Legacy) für jedes Zeichen nach dem dritten Zeichen ausführen, das der Nutzer eingegeben hat, und der Nutzer sieben Zeichen eingibt und dann einen Vorschlag auswählt, für den Sie eine Geocoding API-Anfrage ausführen, betragen die Gesamtkosten 4 Place Autocomplete-Anfragen (Legacy) mit Preis pro Anfrage + Geocoding.1

Wenn sich durch das Verzögern von Anfragen Ihre durchschnittliche Anzahl programmatischer Anfragen auf unter 4 senken lässt, empfehlen wir, die Anleitung für eine leistungsstarke Place Autocomplete-Funktion (Legacy) mit Geocoding API-Implementierung zu beachten. Das Verzögern von Anfragen wird vom Nutzer, der evtl. bei jedem eingegebenen Zeichen mit Vorschlägen rechnet, möglicherweise als Latenz wahrgenommen.

Wenn Sie die Best Practices zur Leistung beachten, erhalten Ihre Nutzer bereits mit weniger eingegebenen Zeichen passende Vervollständigungen.

  1. Informationen zu den Kosten finden Sie in den Preislisten für die Google Maps Platform.

Best Practices für die Leistung

Im Folgenden finden Sie Tipps zum Optimieren der Place Autocomplete (Legacy)-Leistung:

  • Binden Sie in Ihre Place Autocomplete (Legacy)-Implementierung länderspezifische Einschränkungen, eine Standortgewichtung und (bei programmatischen Implementierungen) eine Spracheinstellung ein. Die Spracheinstellung ist bei Widgets nicht erforderlich, weil bei ihnen die Spracheinstellungen aus dem Browser oder vom Mobilgerät des Nutzers übernommen werden.
  • Wenn Place Autocomplete (Legacy) mit einer Karte kombiniert wird, können Sie den Standort anhand des Darstellungsbereichs der Karte gewichten.
  • Wenn ein Nutzer keinen der Vorschläge von Place Autocomplete (Legacy) auswählt, was in der Regel geschieht, wenn es sich bei keinem Vorschlag um die gewünschte Adresse handelt, können Sie anhand der ursprünglichen Nutzereingabe versuchen, relevantere Ergebnisse zu erhalten:
    • Wenn der Nutzer voraussichtlich nur Adressinformationen eingibt, können Sie die ursprüngliche Nutzereingabe bei einem Aufruf der Geocoding API noch einmal verwenden.
    • Wenn Sie davon ausgehen, dass der Nutzer Abfragen für einen bestimmten Ort mithilfe von Name oder Adresse eingibt, verwenden Sie eine Place Details-Anfrage (Legacy). Wenn nur in einer bestimmten Region Ergebnisse erwartet werden, nutzen Sie die Standortgewichtung.
    Bei folgenden Szenarien empfehlen wir, ein Fallback auf die Geocoding API zu nutzen:
    • Nutzer geben Adressen für untergeordnete Gebäude ein, z. B. Adressen für bestimmte Einheiten oder Wohnungen in einem Gebäude. So wird bei der tschechischen Adresse „Stroupežnického 3191/17, Praha“ z. B. eine teilweise Vervollständigung in Place Autocomplete (Legacy) ausgegeben.
    • Wenn Nutzer Adressen mit Präfixen für Straßenabschnitte eingeben, z. B. „23-30 29th St, Queens“ in New York City oder „47-380 Kamehameha Hwy, Kaneohe“ auf der Insel Kauai in Hawaii

Standortgewichtung

Sie können die Ergebnisse zugunsten eines bestimmten Orts gewichten, indem Sie einen location-Parameter und einen radius-Parameter übergeben. Dadurch wird Place Autocomplete (Legacy) angewiesen, vorzugsweise Ergebnisse innerhalb des definierten Bereichs anzuzeigen. Ergebnisse außerhalb des definierten Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter includedRegionCodes können Sie die Ergebnisse so filtern, dass nur Orte in einem bestimmten Land angezeigt werden.

Standorteinschränkung

Wenn Sie einen locationRestriction-Parameter übergeben, können Sie die Ergebnisse auf einen bestimmten Bereich beschränken.

Sie können die Ergebnisse auch auf die Region beschränken, die durch location und den Parameter radius definiert wird, indem Sie den Parameter strictbounds hinzufügen. Dadurch wird der Place Autocomplete-Dienst (Legacy) angewiesen, nur Ergebnisse innerhalb dieser Region zurückzugeben.