Anfrage und Antwort für umgekehrte Geocodierung (Adresssuche)

Entwickler im Europäischen Wirtschaftsraum (EWR)

Der Begriff Geocoding bezeichnet im Allgemeinen die Umwandlung einer Adresse in visuell lesbarer Form in einen Standort auf einer Karte. Der umgekehrte Prozess, also die Umwandlung eines Standortes auf einer Karte in eine Adresse in visuell lesbarer Form, wird als umgekehrte Geocodierung bezeichnet.

Anfragen zur umgekehrten Geocodierung

Erforderliche Parameter

  • latlng: die Breiten- und Längengradkoordinaten des Standorts, für den die am nächsten liegende Adresse in visuell lesbarer Form ausgegeben werden soll.
  • key: Der API-Schlüssel Ihrer Anwendung. Mit diesem Schlüssel wird Ihre Anwendung für die Kontingentverwaltung identifiziert. Informationen zum Abrufen eines Schlüssels

Optionale Parameter

Dies sind die optionalen Parameter, die Sie in eine Reverse-Geocoding-Anfrage einfügen können:

  • language: 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. Diese Liste ist daher möglicherweise nicht vollständig.
    • Wenn language nicht angegeben wird, versucht der Geocoder, die bevorzugte Sprache zu verwenden, die im Accept-Language-Header angegeben ist, oder die Sprache der Domain, von der die Anfrage gesendet wird.
    • Der Geocoder versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Um dieses Ziel zu erreichen, werden Straßenadressen in der lokalen Sprache zurückgegeben, die bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert werden. Dabei wird die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Alle Adresskomponenten werden 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.
  • region: der Regionscode, angegeben als zweistelliger Ländercode der Top-Level-Domain (ccTLD). Der Parameter kann sich auch auf Ergebnisse auswirken, die auf anwendbarem Recht beruhen.
  • result_type: Ein Filter mit einem oder mehreren Adresstypen, die durch ein Pipe-Symbol (|) getrennt sind. Wenn der Parameter mehrere Adresstypen enthält, gibt die API alle Adressen zurück, die mit einem der Typen übereinstimmen. Hinweis zur Verarbeitung: Der Parameter result_type schränkt die Suche nicht auf die angegebenen Adresstypen ein. Stattdessen fungiert result_type als Filter nach der Suche: Die API ruft alle Ergebnisse für die angegebene latlng ab und verwirft dann die Ergebnisse, die nicht mit den angegebenen Adresstypen übereinstimmen. Die folgenden Werte werden unterstützt:

    Typen von Adressen und Adresskomponenten

    Das types-Array im GeocodeResult-Body der Antwort gibt den Adresstyp an. Beispiele für Adresstypen sind eine Straße, ein Land oder eine politische Einheit. Das types-Array im Feld AddressComponents des GeocodeResult-Bodys gibt den Typ der einzelnen Teile der Adresse an. Dazu gehören bspw. Hausnummer oder Land.

    Adressen können mehrere Typen aufweisen. Die Typen können als „Tags“ betrachtet werden. Viele Städte haben z. B. Tags vom Typ political und locality.

    Die folgenden Typen werden sowohl in den Arrays für Adresstypen als auch für Adresskomponententypen unterstützt und zurückgegeben:

    Adresstyp Beschreibung
    street_address Eine genaue Adresse.
    route Eine Straße mit einer Bezeichnung, z. B. „B1“.
    intersection Eine größere Kreuzung, üblicherweise von zwei Hauptstraßen.
    political Eine politische Einheit. Normalerweise zeigt dieser Typ ein Polygon an, das einer öffentlichen Verwaltungseinheit entspricht.
    country Die staatliche politische Einheit (Land) ist normalerweise der Typ mit dem höchsten Rang, der vom Geocoder zurückgegeben wird.
    administrative_area_level_1 Eine öffentliche Verwaltungseinheit eine Stufe unterhalb der Landesebene. In den USA sind diese Verwaltungsebenen die Bundesstaaten. Diese Verwaltungsebenen gibt es nicht in allen Ländern. In den meisten Fällen sind Kurzbezeichnungen dieses Typs eng an die Untereinheiten des Standards ISO 3166-2 und andere gängige Definitionen angelehnt. Eine Garantie hierfür können wir jedoch nicht geben, da unsere Geocoding-Ergebnisse auf verschiedenen Signalen und Standortdaten basieren.administrative_area_level_1
    administrative_area_level_2 Eine öffentliche Verwaltungseinheit zwei Stufen unterhalb der Landesebene. In den USA sind diese Verwaltungsebenen die Countys. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    administrative_area_level_3 Eine öffentliche Verwaltungseinheit drei Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    administrative_area_level_4 Eine öffentliche Verwaltungseinheit vier Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    administrative_area_level_5 Eine öffentliche Verwaltungseinheit fünf Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    administrative_area_level_6 Eine öffentliche Verwaltungseinheit sechs Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    administrative_area_level_7 Eine öffentliche Verwaltungseinheit sieben Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    colloquial_area Eine gängige alternative Bezeichnung für die Einheit.
    locality Eine politische Einheit in Form einer Stadt oder Gemeinde.
    sublocality Eine öffentliche Verwaltungseinheit eine Stufe unterhalb des Ortes. Für einige Standorte wird möglicherweise einer der folgenden zusätzlichen Typen ausgegeben: sublocality_level_1 bis sublocality_level_5. Jede dieser Ebenen entspricht einer Verwaltungseinheit. Je höher die Zahl, desto kleiner das geografische Gebiet.
    neighborhood Ein benanntes Viertel.
    premise Ein benannter Ort, normalerweise ein Gebäude oder ein Komplex von Gebäuden mit einem gemeinsamen Namen.
    subpremise Eine adressierbare Einheit unterhalb der Gebäudeebene, z. B. eine Wohnung, eine Einheit oder ein Apartment.
    plus_code Ein codierter Verweis auf den Standort, der sich aus Breiten- und Längengrad ableiten lässt. Plus Codes können als Ersatz für Adressen verwendet werden, wenn keine Adressen vorhanden sind, z. B. wenn Gebäude keine Hausnummern oder Straßen keine Namen haben. Weitere Informationen finden Sie unter https://plus.codes.
    postal_code Eine Postleitzahl, wie sie zum Adressieren von Postsendungen innerhalb des Landes verwendet wird.
    natural_feature Ein auffälliges Landschaftsmerkmal.
    airport Ein Flughafen.
    park Ein benannter Park.
    point_of_interest Ein benannter POI. In der Regel sind diese POIs bekannte lokale Objekte, die sich keiner anderen Kategorie zuordnen lassen, z. B. das Brandenburger Tor oder der Eiffelturm.

    Eine leere Typenliste bedeutet, dass für eine bestimmte Adresskomponente keine Typen vorhanden sind, wie z. B. ein Lieu-dit in Frankreich.

  • location_type: Ein Filter mit einem oder mehreren durch einen senkrechten Strich (|) getrennten Standorten. Wenn der Parameter mehrere Standorte enthält, gibt die API alle Adressen zurück, die mit einem der Typen übereinstimmen. Hinweis zur Verarbeitung: Der Parameter location_type schränkt die Suche nicht auf die angegebenen Standorte ein. Stattdessen fungiert location_type als Filter nach der Suche: Die API ruft alle Ergebnisse für die angegebene latlng ab und verwirft dann die Ergebnisse, die nicht den angegebenen Standorten entsprechen. Folgende Werte werden unterstützt:
    • "ROOFTOP" gibt nur die Adressen zurück, für die Google Standortinformationen mit einer Genauigkeit bis hin zur Straßenadresse hat.
    • "RANGE_INTERPOLATED" gibt nur die Adressen zurück, die eine Schätzung darstellen (normalerweise auf einer Straße), die anhand von zwei genauen Punkten (wie Kreuzungen) interpoliert wurde. Ein interpolierter Bereich bedeutet in der Regel, dass eine genaue Geocodierung für eine Adresse nicht möglich ist.
    • "GEOMETRIC_CENTER" gibt nur geometrische Mittelpunkte eines Orts wie einer Polylinie (z. B. eine Straße) oder eines Polygons (Region) zurück.
    • "APPROXIMATE" gibt nur die Adressen zurück, die als ungefähre Adressen gekennzeichnet sind.
  • extra_computations: Mit diesem Parameter können Sie die folgenden zusätzlichen Funktionen in der Antwort angeben: Wenn Sie mehrere dieser Funktionen für dieselbe API-Anfrage aktivieren möchten, fügen Sie den Parameter extra_computations für jede Funktion in die Anfrage ein, z. B.: 
    extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Wenn sowohl result_type- als auch location_type-Filter vorhanden sind, gibt die API nur die Ergebnisse zurück, die sowohl mit den result_type- als auch mit den location_type-Werten übereinstimmen. Wenn keiner der Filterwerte akzeptabel ist, gibt die API ZERO_RESULTS zurück.

Beispiel für umgekehrte Geocodierung

Die folgende Abfrage enthält den Breiten- und Längengrad-Wert für einen Ort in Brooklyn:

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452&key=YOUR_API_KEY

Die obige Abfrage gibt folgendes Ergebnis zurück:

{
   "results" : [
      {
         "address_components" : [
            {
               "long_name" : "277",
               "short_name" : "277",
               "types" : [ "street_number" ]
            },
            {
               "long_name" : "Bedford Avenue",
               "short_name" : "Bedford Ave",
               "types" : [ "route" ]
            },
            {
               "long_name" : "Williamsburg",
               "short_name" : "Williamsburg",
               "types" : [ "neighborhood", "political" ]
            },
            {
               "long_name" : "Brooklyn",
               "short_name" : "Brooklyn",
               "types" : [ "sublocality", "political" ]
            },
            {
               "long_name" : "Kings",
               "short_name" : "Kings",
               "types" : [ "administrative_area_level_2", "political" ]
            },
            {
               "long_name" : "New York",
               "short_name" : "NY",
               "types" : [ "administrative_area_level_1", "political" ]
            },
            {
               "long_name" : "United States",
               "short_name" : "US",
               "types" : [ "country", "political" ]
            },
            {
               "long_name" : "11211",
               "short_name" : "11211",
               "types" : [ "postal_code" ]
            }
         ],
         "formatted_address" : "277 Bedford Avenue, Brooklyn, NY 11211, USA",
         "geometry" : {
            "location" : {
               "lat" : 40.714232,
               "lng" : -73.9612889
            },
            "location_type" : "ROOFTOP",
            "viewport" : {
               "northeast" : {
                  "lat" : 40.7155809802915,
                  "lng" : -73.9599399197085
               },
               "southwest" : {
                  "lat" : 40.7128830197085,
                  "lng" : -73.96263788029151
               }
            }
         },
         "place_id" : "ChIJd8BlQ2BZwokRAFUEcm_qrcA",
         "types" : [ "street_address" ]
      },

  ... Additional <code>results[]</code> ...

Beachten Sie, dass der umgekehrte Geocodierer mehr als ein Ergebnis zurückgegeben hat. Die "formatted_address"-Ergebnisse bestehen nicht nur aus Postanschriften, sondern umfassen sämtliche geografischen Bezeichnungen für den Ort. Wenn Sie z. B. einen Punkt in Chicago geocodieren, kann er als Postanschrift, Stadt (Chicago), Bundesstaat (Illinois) oder Land (USA) gekennzeichnet sein. All das wertet der Geocodierer als Adresse. Bei der umgekehrten Geocodierung werden alle genannten Typen als gültige Ergebnisse zurückgegeben.

Die umgekehrte Geocodierung gleicht Verwaltungseinheiten (Länder, Provinzen, Städte, Stadtteile), Adressen und Postleitzahlen ab.

Die vollständige Liste der formatted_address-Werte, die von der vorherigen Abfrage zurückgegeben wurden, finden Sie unten.

{
   "plus_code" : {
      "compound_code" : "P27Q+MCM New York, NY, USA",
      "global_code" : "87G8P27Q+MCM"
   },
   "results" : [
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "street_address" ]
      },
      {
         "formatted_address" : "279 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "premise" ]
      },
      {
         "formatted_address" : "277 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "establishment", "point_of_interest" ]
      },
      {
         "formatted_address" : "291-275 Bedford Ave, Brooklyn, NY 11211, USA",
         ...
         "types" : [ "route" ]
      },
      {
         "formatted_address" : "P27Q+MC New York, NY, USA",
         ...
         "types" : [ "plus_code" ]
      },
      {
         "formatted_address" : "South Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY 11211, USA",
         ...
         "types" : [ "postal_code" ]
      },
      {
         "formatted_address" : "Williamsburg, Brooklyn, NY, USA",
         ...
         "types" : [ "neighborhood", "political" ]
      },
      {
         "formatted_address" : "Kings County, Brooklyn, NY, USA",
         ...
         "types" : [ "administrative_area_level_2", "political" ]
      },
      {
         "formatted_address" : "Brooklyn, NY, USA",
         ...
         "types" : [ "political", "sublocality", "sublocality_level_1" ]
      },
      {
         "formatted_address" : "New York, NY, USA",
         ...
         "types" : [ "locality", "political" ]
      },
      {
         "formatted_address" : "New York, USA",
         ...
         "types" : [ "administrative_area_level_1", "political" ]
      },
      {
         "formatted_address" : "United States",
         ...
         "types" : [ "country", "political" ]
      }
   ],
   "status" : "OK"
}

Diese API gibt verschiedene Arten von Adressen zurück, von den genauen Adressen, d. h. Straßen, bis hin zu weniger genauen politischen Einheiten wie Stadtteilen, Städten, Landkreisen oder Bundesländern. Normalerweise wird die am besten passende Adresse an erster Stelle angezeigt. Wenn Sie nach einem bestimmten Adresstyp suchen möchten, lesen Sie den Abschnitt unten zum Einschränken von Ergebnissen nach Typ. Daher kann sich die Position der Ergebnisse relativ zueinander ändern.

Umgekehrte Geocodierung nach Typ gefiltert

Im folgenden Beispiel werden die zurückgegebenen Adressen so gefiltert, dass nur Adressen mit dem Ortstyp ROOFTOP und dem Adresstyp street_address berücksichtigt werden.

https://maps.googleapis.com/maps/api/geocode/json?latlng=40.714224,-73.961452
&location_type=ROOFTOP&result_type=street_address&key=YOUR_API_KEY

Hinweis:Diese Filter sind nur für die umgekehrte Geocodierung gültig.

Antworten auf umgekehrte Geocodierung

Das Format der Antwort für die umgekehrte Geocodierung ist dasselbe wie das der Geocodierungsantwort. Geocoding-Antworten Im Folgenden finden Sie die Statuscodes, die in den Antworten des umgekehrten Geocoding möglich sind.

Statuscodes für die umgekehrte Geocodierung

Das Feld "status" im Geocoding-Antwortobjekt enthält den Status der Anfrage und möglicherweise Debugging-Informationen, mit denen Sie herausfinden können, warum die Rückwärtssuche nicht funktioniert. Das Feld "status" kann die folgenden Werte enthalten:

  • "OK" gibt an, dass keine Fehler aufgetreten sind und mindestens eine Adresse zurückgegeben wurde.
  • "ZERO_RESULTS" gibt an, dass die umgekehrte Geocodierung erfolgreich war, aber keine Ergebnisse zurückgegeben wurden. Dieser Status kann ausgegeben werden, wenn dem Geocoder ein latlng-Element an einem entfernten Standort übergeben wurde.
  • "OVER_QUERY_LIMIT" gibt an, dass Sie Ihr Kontingent überschritten haben.
  • "REQUEST_DENIED" gibt an, dass die Anfrage abgelehnt wurde. Möglicherweise enthält die Anfrage einen result_type- oder location_type-Parameter, aber keinen API-Schlüssel.
  • "INVALID_REQUEST" weist in der Regel auf eines der folgenden Probleme hin:
    • Die Anfrage (address, components oder latlng) fehlt.
    • Es wurde ein ungültiges result_type oder location_type angegeben.
  • "UNKNOWN_ERROR" gibt an, dass die Anfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Möglicherweise ist die Anfrage erfolgreich, wenn Sie es noch einmal versuchen.

Umgekehrte Geocodierung von Plus Codes

Das Feld plus_code in der Geocoding-Antwort enthält einen Plus Code, der den angefragten Breiten- und Längengrad am besten annähert. Außerdem enthält das JSON-Ergebnis-Array in den meisten Fällen ein vollständiges Geocoding-Ergebnis mit dem Typ plus_code und einer Adresse mit einem Pluscode. Der Abstand zwischen dem decodierten Plus Code und dem Anfragepunkt liegt garantiert unter 10 Metern.