Place Autocomplete (alte Version)

Place Autocomplete (Legacy) ist ein Webdienst, der als Antwort auf eine HTTP-Anfrage Ortsvorschläge zurückgibt. In der Anfrage werden ein Suchstring und optionale geografische Grenzen angegeben. Der Dienst kann verwendet werden, um eine automatische Vervollständigung für textbasierte geografische Suchanfragen bereitzustellen. Dabei werden Orte wie Unternehmen, Adressen und POIs zurückgegeben, während der Nutzer Text eingibt.

Place Autocomplete-Anfragen (Legacy)

Place Autocomplete (Legacy) ist Teil der Places API und verwendet denselben API-Schlüssel und dieselben Kontingente wie die 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. Beispiel: Der globale URL-Escape-Code 849VCWC8+R9 ist 849VCWC8%2BR9.
• Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort. Beispiel: Der URL-codierte Plus Code CWC8+R9 Mountain View, CA, USA lautet CWC8%2BR9%20Mountain%20View%20CA%20USA.

Die zurückgegebenen Vervollständigungen sollen dem Nutzer präsentiert werden, um ihm die Auswahl des gewünschten Orts zu erleichtern. Sie können eine Place Details (Legacy)-Anfrage senden, um weitere Informationen zu den zurückgegebenen Orten zu erhalten.

Eine Place Autocomplete (Legacy)-Anfrage ist eine HTTP-URL im folgenden Format:

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

Dabei kann output einen der folgenden Werte haben:

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

Für eine Place Autocomplete-Anfrage (Legacy) sind bestimmte Parameter erforderlich. 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. Der Place Autocomplete-Dienst gibt mögliche Übereinstimmungen basierend auf diesem String zurück und sortiert die Ergebnisse nach erkannter Relevanz.

Optionale Parameter

Komponenten

Eine Gruppierung von Orten, auf die Sie Ihre Ergebnisse beschränken möchten. Sie können Komponenten verwenden, um nach bis zu fünf Ländern zu 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 Damit werden die Ergebnisse auf Orte in den USA und den nicht eingegliederten organisierten Gebieten beschränkt.

Sprache

Die Sprache, in der die 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, wobei die bevorzugte Sprache berücksichtigt wird. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die von der ersten Komponente ausgewählt wird.
• Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstgelegene Übereinstimmung.
• 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. Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sind, 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. Diese muss als latitude,longitude angegeben werden. Der Parameter radius muss ebenfalls angegeben werden, wenn ein Standort angegeben wird. Wenn radius nicht angegeben ist, wird der Parameter location ignoriert.

locationbias

Ergebnisse in einem bestimmten Bereich bevorzugen, indem Sie entweder einen Radius und einen 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, die IP-Adresse zu berücksichtigen. Übergeben Sie den String ipbias (diese Option hat keine zusätzlichen Parameter).
• 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. Beachten Sie, dass Ost-/Westwerte auf den Bereich -180 bis 180 und Nord-/Südwerte auf den Bereich -90 bis 90 beschränkt sind.

locationrestriction

Sie können die Ergebnisse auf einen bestimmten Bereich beschränken, indem Sie entweder einen Radius und Breiten-/Längengrad oder zwei Paare aus Breiten-/Längengrad 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. Beachten Sie, dass Ost-/Westwerte auf den Bereich -180 bis 180 und Nord-/Südwerte auf den Bereich -90 bis 90 beschränkt sind.

kompensiert

Die Position des letzten Zeichens im Eingabebegriff, das der Dienst für die Vervollständigung verwendet. Wenn die Eingabe beispielsweise Google und der Offset 3 ist, wird der Dienst mit Goo abgeglichen. Der durch den Offset bestimmte String wird nur mit dem ersten Wort im Eingabebegriff 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 ist, verwendet der Dienst den gesamten Begriff. Der Offset sollte im Allgemeinen auf die Position des Text-Carets festgelegt werden.

origin

Der Ausgangspunkt, von dem aus die Luftlinie zum Ziel berechnet werden soll (zurückgegeben als distance_meters). 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 Ortsergebnisse zurückgegeben werden sollen. Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Kreises gewichten. Dadurch werden vom Places-Dienst vorzugsweise Ergebnisse für Orte angezeigt, die sich innerhalb dieses Kreises befinden. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden.

Der Radius wird je nach Art der Suche und anderen Parametern automatisch auf einen Höchstwert begrenzt.

• Automatische Vervollstä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-Fehler ausgegeben.
• Query Autocomplete: 50.000 Meter
• Text Search: 50.000 Meter

Region

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

sessiontoken

Ein zufälliger String, der eine Sitzung für die automatische 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 von „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.
• Für jede Sitzung muss ein neues Token generiert werden. 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

Es werden nur Orte zurückgegeben, die sich genau innerhalb der durch location und radius definierten Region befinden. Dies ist eine Einschränkung, keine Gewichtung. 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. Beispielsweise wird ein Hotel, in dem Essen serviert wird, möglicherweise nur mit types=lodging und nicht mit types=restaurant zurückgegeben.

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 kombinieren.

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 Einrichtungen, die den String „Amoeba“ enthalten, in einem Gebiet mit dem Mittelpunkt San Francisco, Kalifornien:

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 -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:

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 -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:

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

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:

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

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

In diesen Beispielen müssen Sie den API-Schlüssel 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 ist. Die folgenden Ergebnisse sind ein Beispiel dafür, was für eine Abfrage mit den folgenden Parametern zurückgegeben werden kann:

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

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

{
  "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 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

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) Results. 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 zur Verarbeitung 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 ein Begrenzungsrahmen an einem abgelegenen Ort übergeben wurde.
• INVALID_REQUEST: Die API-Anfrage war fehlerhaft, in der Regel aufgrund des fehlenden Parameters input.
• OVER_QUERY_LIMIT, der auf Folgendes hinweist:
  • Sie haben 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 ein von Ihnen festgelegtes 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 häufig gestellten Fragen zu Maps.
• REQUEST_DENIED: Ihre Anfrage wurde abgelehnt. Dies hat in der Regel folgende Gründe:
  • 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 einer Suche zurückgibt, werden sie in einem predictions-Array platziert. Auch wenn der Dienst keine Ergebnisse zurückgibt (z. B. wenn sich der location an einem anderen Ort befindet), wird ein leeres predictions-Array zurückgegeben. XML-Antworten bestehen aus null oder mehr <prediction>-Elementen.

PlaceAutocompletePrediction

PlaceAutocompleteMatchedSubstring

PlaceAutocompleteStructuredFormat

PlaceAutocompleteTerm

Place Autocomplete (Legacy) optimieren

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

Allgemeine Richtlinien:

• Am schnellsten lässt sich eine funktionsfähige Benutzeroberfläche mit dem Place Autocomplete (Legacy)-Widget der Maps JavaScript API, dem Place Autocomplete (Legacy)-Widget des Places SDK for Android oder dem UI-Steuerelement für Place Autocomplete (Legacy) des Places SDK for iOS entwickeln.
• Machen Sie sich zu Beginn mit den wichtigsten Datenfeldern von Place Autocomplete (Legacy) 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, wenn die API einen Fehler zurückgibt, damit die Anwendung fehlertolerant reagiert.
• Die Anwendung sollte Anfragen weiter verarbeiten und weiter funktionieren, auch wenn keine Auswahl getroffen wird.

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 Preise für die SKU „Autocomplete – Per Request“ 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 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 Funktion „Place Autocomplete (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 durchschnittliche Anzahl von Anfragen für die Tabelle zu ermitteln, analysieren Sie, wie viele Zeichen Nutzer durchschnittlich eingeben, bevor sie in Ihrer Anwendung einen Place Autocomplete-Vorschlag (Legacy) auswählen.

Sitzungsbasierte Place Autocomplete-Anfragen (Legacy) mit Place Details-Anfragen (Legacy)

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

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 Place Autocomplete (Legacy)-Datenfelder angefordert werden.

Programmatische Implementierung
Verwenden Sie für Place Autocomplete (Legacy)-Anfragen ein Sitzungstoken. Binden Sie die folgenden Parameter ein, wenn Sie Place Details (Legacy) für die ausgewählte Vervollständigung 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 von Place Autocomplete (Legacy) angegeben werden

Place Autocomplete (Legacy) pro Anfrage mit der Geocoding API

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. Vier Autocomplete – Per Request-Anfragen plus ein Geocoding API-Aufruf für die ausgewählte Ortsvervollständigung kosten weniger als eine Place Autocomplete (Legacy)-Sitzung.¹

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

Sitzungsbasiertes Place Autocomplete (Legacy) für Anwendungen, die nur Adressen verwenden

Nutzen Sie das sitzungsbasierte Place Autocomplete-Modell (Legacy) mit Place Details-Anfragen (Legacy).
Da die durchschnittliche Anzahl der Anfragen, die Sie voraussichtlich stellen, bevor ein Nutzer eine Place Autocomplete (Legacy)-Vervollständigung auswählt, die Kosten für die Preisgestaltung pro Sitzung übersteigt, sollten Sie bei Ihrer Implementierung von Place Autocomplete (Legacy) ein Sitzungstoken sowohl für die Place Autocomplete (Legacy)-Anfragen als auch für die zugehörige Place Details (Legacy)-Anfrage verwenden. Pro Sitzung. ¹

Widget-Implementierung
Die Sitzungsverwaltung ist automatisch in das JavaScript, Android oder iOS integriert. Das umfasst sowohl Place Autocomplete (Legacy)-Anfragen als auch die Place Details (Legacy)-Anfrage 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 (Legacy)-Anfragen 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-Antwort (Legacy)
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 (Legacy)-Anfragen für jedes Zeichen stellen, nachdem der Nutzer das dritte Zeichen eingegeben hat, und der Nutzer sieben Zeichen eingibt und dann eine Vervollständigung auswählt, für die Sie eine Geocoding API-Anfrage stellen, entsprechen die Gesamtkosten vier Place Autocomplete (Legacy)-Anfragen mit Preis pro Anfrage plus Geocoding.¹

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.

Best Practices für die Leistung

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

• 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, die Adressen von Untereinheiten eingeben, 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

Wenn Sie die Parameter location und radius weitergeben, können Sie die Ergebnisse zugunsten eines festgelegten Bereichs gewichten. Dadurch wird Place Autocomplete (Legacy) angewiesen, bevorzugt Ergebnisse innerhalb des definierten Bereichs anzuzeigen. Ergebnisse außerhalb dieses 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

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

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