Es kann losgehen!

Bevor Sie mit der Entwicklung beginnen, lesen Sie bitte unsere Entwicklerdokumentation.

Den Google Places API Web Service aktivieren

Zum Einstieg führen wir Sie durch die Google Developers Console, wo Sie vorab Folgendes tun müssen:

  1. Ein Projekt erstellen oder auswählen
  2. Den Google Places API Web Service aktivieren
  3. Zugehörige Schlüssel erstellen
Weiter

Orte automatisch vervollständigen

Der Dienst zum automatischen Vervollständigen von Orten ist ein Webdienst, der Ortsvorhersagen als Antwort auf eine HTTP-Anforderung zurückgibt. Die Anforderung enthält eine Suchzeichenfolge in Textform und optionale geografische Grenzen. Sie können diesen Dienst verwenden, um die automatische Vervollständigungsfunktion für textbasierte geografische Suchvorgänge bereitzustellen. Während der Benutzer noch tippt, gibt der Dienst Orte, wie Unternehmen, Adressen und Sehenswürdigkeiten zurück.

Anforderungen mit automatischer Vervollständigung von Orten

Der Dienst zur automatischen Ortsvervollständigung (Place Autocomplete) ist Teil der Google Places API Web Service und nutzt den API-Schlüssel und die Kontingente zusammen mit der Google Places API Web Service.

Der automatische Dienst zur Vervollständigung von Orten kann Übereinstimmungen sowohl mit vollständigen Wörtern als auch mit Teilzeichenfolgen finden. Anwendungen können daher Abfragen senden, während der Benutzer tippt, um Ortsvorhersagen spontan zurückzugeben.

Die zurückgegebenen Vorhersagen werden dem Benutzer angezeigt, um ihm bei der Auswahl des gewünschten Orts zu helfen. Sie können eine Anforderung von Ortsdaten senden, um mehr Informationen zu den zurückgegebenen Orten zu erfahren.

Eine Anforderung mit Autovervollständigung von Orten ist eine HTTP POST-Anforderung der folgenden Form:

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

wobei output einen der folgenden Werte haben kann:

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

Es sind bestimmte Parameter für die Initiierung einer Anforderung mit Autovervollständigung von Orten erforderlich. Standardmäßig werden alle Parameter in URLs durch ein kaufmännisches Und (&) getrennt. Die Liste der Parameter und deren mögliche Werte sind unten aufgeführt.

Erforderliche Parameter

  • input — Die Zeichenfolge, anhand der gesucht wird. Der Dienst zur Autovervollständigung von Orten gibt mögliche Übereinstimmungen basierend auf dieser Zeichenfolge zurück und ordnet die Ergebnisse nach erkannter Relevanz.
  • key — der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für das Kontingentmanagement. Weitere Informationen finden Sie unter Schlüssel anfordern. Google Maps APIs Premium Plan-Kunden müssen das API-Projekt verwenden, das beim Premium Plan-Kauf für sie erstellt wurde.

Optionale Parameter

  • offset — die Position des letzten Zeichens im Eingabebegriff, das der Dienst für den Übereinstimmungsabgleich von Vorhersagen verwendet. Beispiel: Wenn die Eingabe „Google“ lautet und offset den Wert 3 hat, wird der Dienst nach Übereinstimmungen mit „Goo“ suchen. Die durch offset festgelegte Zeichenfolge wird nur mit dem ersten Wort im Eingabebegriff abgeglichen. Beispiel: Wenn die Eingabe „Google abc“ lautet und offset den Wert 3 hat, wird der Dienst nach Übereinstimmungen mit „Goo abc“ suchen. Wird kein Wert für offset angegeben, verwendet der Dienst den gesamten Begriff. Der Wert offset sollte normalerweise auf die Position des Textcursors gesetzt werden.
  • location — der Punkt, um den herum Sie Ortsdaten abrufen möchten. Er muss als Breitengrad,Längengrad angegeben werden.
  • radius — der Abstand (in Metern), innerhalb dessen Ortsergebnisse zurückgegeben werden sollen. Beachten Sie, dass die Angabe von radius die Ergebnisse auf den angegebenen Bereich beschränkt, aber nicht vollständig darauf einschränkt. Weitere Informationen finden Sie unten unter Standort-Biasing und Standorteinschränkung.
  • language — der Sprachencode gibt an, in welcher Sprache die Ergebnisse vorzugsweise zurückgegeben werden sollen. Die ausgewählte Sprache hat auch Einfluss auf die Anzeige der Suchergebnisse. Ergebnisse in der ausgewählten Sprache werden möglicherweise vorrangig behandelt. Weitere Informationen zu Sprachen und ihren Codes finden Sie in der Liste der unterstützten Sprachen. Beachten Sie, dass die unterstützten Sprachen häufig aktualisiert werden. Die Liste ist ggf. nicht vollständig. Wurde keine Sprache angegeben, versucht der Dienst zur Autovervollständigung von Orten, die native Sprache der Domäne zu verwenden, aus der die Anforderung gesendet wurde.
  • types — die Typen der zurückzugebenden Ortsergebnisse. Die Ortstypen finden Sie unten. Wurde kein Typ angegeben, werden alle Typen zurückgegeben.
  • components — eine Gruppierung von Orten, auf die Sie Ihre Ergebnisse beschränken möchten. Aktuell können Sie mit components nach Ländern filtern. Das Land muss als Ländercode in Form einer Zeichenfolge aus zwei Zeichen übergeben werden, die mit ISO 3166-1 ALPHA-2 kompatibel ist. Beispiel: components=country:fr schränkt Ihre Ergebnisse auf Orte in Frankreich ein.
  • strictbounds — gibt nur die Orte zurück, die sich strikt innerhalb der durch location und radius definierten Region befinden. Hierbei handelt es sich um eine Einschränkung – nicht um einen Bias: Ergebnisse außerhalb der Region werden auch dann nicht zurückgegeben, wenn sie der Nutzereingabe entsprechen.

Standort-Biasing

Sie können Ergebnisse auf einen bestimmten Umkreis beschränken, indem Sie die Parameter location und radius übergeben. Dies weist den Autovervollständigungsdienst für Orte an, vorzugsweise Ergebnisse innerhalb dieses Kreises anzuzeigen. Ergebnisse außerhalb dieses Bereichs können aber trotzdem angezeigt werden. Mit dem Parameter components können Sie Ergebnisse filtern, sodass nur noch Orte angezeigt werden, die innerhalb eines bestimmten Landes liegen.

Tipp: Ergebnisse zu Einrichtungen werden normalerweise nicht hoch genug eingestuft, um in den Ergebnisse aufzutauchen, wenn der Suchbereich sehr groß ist. Falls Sie möchten, dass Einrichtungen in gemischten Einrichtungs-/Geocodeergebnisse erscheinen, geben Sie einen kleineren Radius an. Verwenden Sie alternativ types=establishment, um die Ergebnisse auf Unternehmen zu beschränken.

Standorteinschränkung

Indem Sie den Parameter strictbounds hinzufügen, können Sie auch Ergebnisse auf eine Region beschränken, die durch die Parameter location und radius definiert ist. Der Place Autocomplete-Dienst wird auf diese Weise angewiesen, nur Ergebnisse aus dieser Region zurückzugeben.

Ortstypen

Möglicherweise möchten Sie Ergebnisse aus einer Anforderung mit Autovervollständigung auf einen bestimmten Typ beschränken, indem Sie den Parameter types übergeben. Der Parameter legt einen Typ oder eine Typauflistung fest, wie in den unterstützten Typen nachfolgend gezeigt. Wurde nichts angegeben, werden alle Typen zurückgegeben. Üblicherweise ist nur ein Typ zulässig. Die einzige Ausnahme ist, dass Sie die Typen geocode und establishment gefahrlos kombinieren können. Dies hat aber denselben Effekt, wie gar keinen Typ anzugeben. Folgende Typen werden unterstützt:

  • Über geocode wird der Dienst zur Autovervollständigung von Orten angewiesen, nur Geocodierungsergebnisse anstelle von Unternehmensergebnissen zurückzugeben. Im Allgemeinen verwenden Sie diese Anforderung, um die Ergebnisse eindeutig zu machen, in denen der angegebene Standort möglicherweise unbestimmt ist.
  • address weist den Dienst zur Autovervollständigung von Orten an, nur Geocodierungsergebnisse anstelle von genauen Adressen zurückzugeben. Im Allgemeinen verwenden Sie diese Anforderung, wenn Sie wissen, dass der Benutzer nach einer vollständig angegebenen Adresse sucht.
  • establishment weist den Dienst Place Autocomplete an, nur Unternehmensergebnisse zurückzugeben.
  • Die Typauflistung (regions) weist den Ortsdienst an, nur Ergebnisse zurückzugeben, die folgenden Typen entsprechen:
    • locality
    • sublocality
    • postal_code
    • country
    • administrative_area_level_1
    • administrative_area_level_2
  • Mit der Typauflistung (cities) wird der Dienst „Places“ angewiesen, nur Ergebnisse zurückzugeben, die den Typen locality oder administrative_area_level_3 entsprechen.

Beispiele von Anforderungen mit automatischer Vervollständigung

Eine Anforderung für Einrichtungen, die die Zeichenfolge „Amoeba“ im Gebiet von San Francisco, Kalifornien, enthalten.

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&key=YOUR_API_KEY

Die gleiche Anforderung, beschränkt auf Ergebnisse im Umkreis von 500 Metern um Ashbury St & Haight St, San Francisco:

https://maps.googleapis.com/maps/api/place/autocomplete/xml?input=Amoeba&types=establishment&location=37.76999,-122.44696&radius=500&strictbounds&key=YOUR_API_KEY

Eine Anforderung für Adressen, die „Vict“ in den Ergebnissen in französischer Sprache enthalten:

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

Eine Anforderung für Adressen, die „Vict“ in den Ergebnissen in brasilianischem Portugiesisch enthalten:

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

Beachten Sie, dass Sie den API-Schlüssel in diesen Beispielen durch Ihren eigenen Schlüssel ersetzen müssen.

Antworten mit automatischer Vervollständigung von Orten

Antworten mit automatischer Vervollständigung von Orten werden in dem Format zurückgegeben, das im Flag output im URL-Pfad der Anforderung angegeben wurde. Die Ergebnisse unten zeigen, welche Antworten auf eine Abfrage mit folgenden Parametern zurückgegeben werden:

input=Paris&types=geocode

JSON
{
  "status": "OK",
  "predictions" : [
      {
         "description" : "Paris, France",
         "id" : "691b237b0322f28988f3ce03e321ff72a12167fd",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJD7fiBh9u5kcRYJSMaMOCCwQ",
         "reference" : "CjQlAAAA_KB6EEceSTfkteSSF6U0pvumHCoLUboRcDlAH05N1pZJLmOQbYmboEi0SwXBSoI2EhAhj249tFDCVh4R-PXZkPK8GhTBmp_6_lWljaf1joVs1SH2ttB_tw",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris"
            },
            {
               "offset" : 7,
               "value" : "France"
            }
         ],
         "types" : [ "locality", "political", "geocode" ]
      },
      {
         "description" : "Paris Avenue, Earlwood, New South Wales, Australia",
         "id" : "359a75f8beff14b1c94f3d42c2aabfac2afbabad",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJrU3KAHG6EmsR5Uwfrk7azrI",
         "reference" : "CkQ2AAAARbzLE-tsSQPgwv8JKBaVtbjY48kInQo9tny0k07FOYb3Z_z_yDTFhQB_Ehpu-IKhvj8Msdb1rJlX7xMr9kfOVRIQVuL4tOtx9L7U8pC0Zx5bLBoUTFbw9R2lTn_EuBayhDvugt8T0Oo",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Avenue"
            },
            {
               "offset" : 14,
               "value" : "Earlwood"
            },
            {
               "offset" : 24,
               "value" : "New South Wales"
            },
            {
               "offset" : 41,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
      {
         "description" : "Paris Street, Carlton, New South Wales, Australia",
         "id" : "bee539812eeda477dad282bcc8310758fb31d64d",
         "matched_substrings" : [
            {
               "length" : 5,
               "offset" : 0
            }
         ],
         "place_id" : "ChIJCfeffMi5EmsRp7ykjcnb3VY",
         "reference" : "CkQ1AAAAAERlxMXkaNPLDxUJFLm4xkzX_h8I49HvGPvmtZjlYSVWp9yUhQSwfsdveHV0yhzYki3nguTBTVX2NzmJDukq9RIQNcoFTuz642b4LIzmLgcr5RoUrZhuNqnFHegHsAjtoUUjmhy4_rA",
         "terms" : [
            {
               "offset" : 0,
               "value" : "Paris Street"
            },
            {
               "offset" : 14,
               "value" : "Carlton"
            },
            {
               "offset" : 23,
               "value" : "New South Wales"
            },
            {
               "offset" : 40,
               "value" : "Australia"
            }
         ],
         "types" : [ "route", "geocode" ]
      },
  ...additional results ...
      
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>
  <place_id>ChIJD7fiBh9u5kcRYJSMaMOCCwQ</place_id>
  <reference>CiQRAAAAJm0CiCHIC8C4GOjREdm3QtHYhMyFaUXKWAbGSaZImQ8SECnHAhpcuZaoSr0_TKfeHvwaFHMIq_BmUccTC4mt6EWVNMa67Xuq</reference>
  <id>691b237b0322f28988f3ce03e321ff72a12167fd</id>
  <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>
 </prediction>
 <prediction>
  <description>Paris, TX, United States</description>
  <type>colloquial_area</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJrU3KAHG6EmsR5Uwfrk7azrI</place_id>
  <reference>CiQcAAAArNRoGmiHh0PNVH5LSnJEbT5L7DfUE-APvTfYac9Ta5USEIfAOzXTkqTpioZX9qeevY8aFPgN_H6qcRnGLqPUq4zkOE-_g-ul</reference>
  <id>029556239a911839382f42ec36c5ce2b85be9be3</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>TX</value>
   <offset>7</offset>
  </term>
  <term>
   <value>United States</value>
   <offset>11</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
 <prediction>
  <description>Paris, Ontario, Canada</description>
  <type>locality</type>
  <type>political</type>
  <type>geocode</type>
  <place_id>ChIJCfeffMi5EmsRp7ykjcnb3VY</place_id>
  <reference>CiQaAAAApuD3Th6N5_EcJjKw0umu_IonagFPBo9idTf7WB8-cw8SEGS5wSvHzhuUvCqPH-uM5B8aFIedLGNSuh5M5eqWdBJCtc0Ibvd0</reference>
  <id>e7ac9c89d4a590305242b0cb5bf43064027223c9</id>
  <term>
   <value>Paris</value>
   <offset>0</offset>
  </term>
  <term>
   <value>Ontario</value>
   <offset>7</offset>
  </term>
  <term>
   <value>Canada</value>
   <offset>16</offset>
  </term>
  <matched_substring>
   <offset>0</offset>
   <length>5</length>
  </matched_substring>
 </prediction>
</AutocompletionResponse>

Eine JSON-Antwort enthält zwei Stammelemente:

  • status enthält Metadaten zur Anforderung. Weitere Informationen finden Sie weiter unten unter Statuscodes.
  • predictions enthält ein Ortsarray mit Informationen zum Ort. Weitere Informationen zu diesen Ergebnissen finden Sie unter Ergebnisse mit automatischer Vervollständigung von Orten. Google Places API Web Service gibt maximal 5 Ergebnisse zurück.

Von besonderem Interesse bei den Ergebnissen sind die Elemente place_id, die dazu verwendet werden können, weitere Details zum Ort über eine separate Abfrage anzufordern. Weitere Informationen finden Sie unter Anforderungen zu Ortsdaten.

Weitere Hilfe zum Parsen von JSON-Antworten finden Sie unter Verarbeitung von JSON mit JavaScript.

Eine XML-Antwort besteht aus dem einzigen Element <AutocompletionResponse> mit zwei Typen untergeordneter Elemente:

  • Das Element <status>, das Metadaten zur Anforderung enthält. Weitere Informationen finden Sie weiter unten unter Statuscodes.
  • Kein oder mehrere Elemente <prediction>, die jeweils Informationen zu einem Ort enthalten. Weitere Informationen zu diesen Ergebnissen finden Sie unter Ergebnisse mit automatischer Vervollständigung von Orten. Google Places API Web Service gibt maximal 5 Ergebnisse zurück.

Sie sollten json als das bevorzugte Ausgabe-Flag verwenden, sofern Ihre Anwendung nicht aus irgendeinem Grund xml verlangt. Die Verarbeitung von XML-Strukturen erfordert einige Sorgfalt. Knoten und Elemente müssen präzise referenziert werden. Weitere Hilfe zur XML-Verarbeitung finden Sie in Parsing von XML mit XPath.

Statuscodes

Das Feld status im Objekt „Place Autocomplete response“ enthält den Status der Anforderung und kann auch Debuginformationen enthalten, die Ihnen helfen sollen, herauszufinden, warum die Anforderung mit automatischer Ortsvervollständigung nicht erfolgreich war. Das Feld status kann folgende Werte enthalten:

  • OK gibt an, dass keine Fehler aufgetreten sind und mindestens ein Ergebnis zurückgegeben wurde.
  • ZERO_RESULTS gibt an, dass die Suche erfolgreich war, aber keine Ergebnisse zurückgegeben hat. Dies kann eintreten, wenn der Suche das Objekt bounds in einem Remotestandort übergeben wurde.
  • OVER_QUERY_LIMIT gibt an, dass Sie das Kontingent überschritten haben.
  • REQUEST_DENIED gibt an, dass die Anforderung abgelehnt wurde. Dies geschieht in der Regel, wenn der gültige Parameter key fehlt.
  • INVALID_REQUEST gibt normalerweise an, dass der Parameter input fehlt.

Fehlermeldungen

Wenn der Ortsdienst einen anderen Statuscode als OK zurückgibt, wird ggf. das zusätzliche Feld error_message im Antwortobjekt angezeigt. Dieses Feld enthält weitere detaillierte Informationen zu den Gründen für den zurückgegebenen Statuscode.

Ergebnisse mit automatischer Vervollständigung von Orten

Wenn der Ortsdienst JSON-Ergebnisse von einer Suche zurückgibt, stellt er diese in das Array predictions. Auch wenn der Dienst keine Ergebnisse zurückgibt (wie wenn location remote ist), gibt er dennoch das leere Array predictions zurück. XML-Antworten bestehen aus keinem oder mehreren Elementen vom Typ <prediction>.

Jedes Vorhersageergebnis hat folgende Felder:

  • description enthält den Namen für das zurückgegebene Ergebnis in einer vom Menschen lesbaren Form. Bei Ergebnissen für establishment handelt es sich normalerweise um den Namen des Unternehmens.
  • place_id ist eine ID in Textform, die einen Ort eindeutig bezeichnet. Um Informationen zum Ort abzurufen, tragen Sie diese ID in das Feld placeId einer Google Places API Web Service-Anforderung ein. Weitere Informationen zu Orts-IDs finden Sie unter Orts-ID Übersicht.
  • reference enthält ein eindeutiges Token, mit dem Sie zusätzliche Informationen zum Ort mittels einer Ortsdatenanforderung abrufen können. Auch wenn dieses Token den Ort eindeutig identifiziert, gilt das umgekehrt nicht. Ein Ort kann viele gültige Referenztokens haben. Es kann nicht garantiert werden, dass dasselbe Token für einen bestimmten Ort in anderen Suchvorgängen zurückgegeben wird. Hinweis: reference ist gegenüber place_id veraltet. Weitere Informationen finden Sie auf dieser Seite unter Hinweis zur Veralterung.
  • id enthält eine eindeutige, stabile ID zur Bezeichnung dieses Orts. Die ID kann nicht zum Anfordern von Informationen zu diesem Ort verwendet werden, aber sie kann zum Konsolidieren von Daten zu diesem Ort und zur Überprüfung der Identität eines Orts aus mehreren Suchvorgängen dienen. Hinweis: id ist gegenüber place_id veraltet. Weitere Informationen finden Sie auf dieser Seite unter Hinweis zur Veralterung.
  • terms enthält ein Array von Begriffen, die jeden Abschnitt der zurückgegebenen Beschreibung identifizieren (ein Abschnitt der Beschreibung endet in der Regel mit einem Komma). Jeder Eintrag im Array hat ein Feld value, das den Text des Begriffs enthält, sowie ein Feld offset, das die Startposition dieses Begriffs in der Beschreibung in Unicode-Zeichen festlegt.
  • types enthält ein Array der für diesen Platz geltenden Typen. Beispiel: [ "political", "locality" ] oder [ "establishment", "geocode" ].
  • matched_substrings enthält ein Array mit offset-Wert und length. Sie beschreiben die Position des eingegebenen Begriffs im Text des Vorhersageergebnisses, sodass der Begriff bei Bedarf hervorgehoben werden kann.

Der Parameter sensor

Zuvor war in Google Places API Web Service die Angabe des Parameters sensor erforderlich. Damit wurde festgelegt, ob seitens der Anwendung ein Sensor zur Ermittlung des Benutzerstandorts verwendet wurde. Dieser Parameter wird nicht mehr benötigt.

Feedback geben zu...

location_on
Google Places API Web Service