Anfrage und Antwort für umgekehrte Geocodierung (Adresssuche)

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: 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. Dieser Schlüssel identifiziert Ihre Anwendung für die Kontingentverwaltung. Weitere Informationen zum Abrufen eines Schlüssels

Optionale Parameter

Dies sind die optionalen Parameter, die Sie in eine Anfrage für den umgekehrten Geocoding einfügen können:

  • language: Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.
    • Weitere Informationen finden Sie in der Liste der unterstützten Sprachen. Die unterstützten Sprachen werden regelmäßig von Google aktualisiert. Diese Liste ist daher möglicherweise nicht vollständig.
    • Wird language nicht angegeben, versucht der Geocoder, Verwenden Sie die bevorzugte Sprache, wie in den Accept-Language-Headers oder in der Muttersprache des Domain, von der die Anfrage gesendet wird.
    • Der Geocoder gibt sein Bestes, um eine Adresse anzugeben, die sowohl für Nutzer als auch für Einheimische lesbar ist. Um dieses Ziel zu erreichen, gibt Adressen in der Landessprache zurück, transliteriert in eine falls notwendig für den Nutzer lesbar, unter Berücksichtigung der Sprache. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Die Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
    • Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet der Geocoder die beste Übereinstimmung.
  • region: der als ccTLD angegebene Regionscode (Top-Level-Domain) aus zwei Zeichen. Der Parameter kann sich auch auf Ergebnisse auf der Grundlage geltender Gesetze.
  • result_type (ein Filter aus einem oder mehreren Adresstypen) durch ein Pipe-Zeichen (|) getrennt. Wenn der Parameter mehrere Adresstypen verwenden, gibt die API alle Adressen zurück, die einem der Typen entsprechen. Hinweis zur Verarbeitung: Der Parameter result_type enthält keine restrict: die Suche auf die angegebenen Adresstypen Vielmehr sollte der result_type fungiert als Filter nach der Suche: Die API ruft alle Ergebnisse für die angegebene latlng und verwirft diese Ergebnisse dann die nicht mit dem/den angegebenen Adresstyp(en) übereinstimmen. Die folgenden Werte sind unterstützt:
    • street_address gibt eine genaue Adresse an.
    • route gibt eine Straße mit einer Bezeichnung an, z. B. „B1“.
    • intersection gibt eine größere Kreuzung, üblicherweise von 2 Hauptstraßen an.
    • political gibt eine politische Einheit an. Dieser Typ stellt meistens ein Polygon einer öffentlichen Einrichtung dar.
    • country gibt eine staatliche politische Einheit (Land) an und ist normalerweise der Typ mit dem höchsten Rang, der vom Geocoder zurückgegeben wird.
    • administrative_area_level_1 gibt eine öffentliche Verwaltungseinheit 1 Stufe unterhalb der Landesebene an. In den USA sind diese Verwaltungsebenen z. B. 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_2 gibt eine öffentliche Verwaltungseinheit 2 Stufen unterhalb der Landesebene an. In den USA sind diese Verwaltungsebenen z. B. die Countys. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    • administrative_area_level_3 gibt eine öffentliche Verwaltungseinheit 3 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    • administrative_area_level_4 gibt eine öffentliche Verwaltungseinheit 4 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    • administrative_area_level_5 gibt eine öffentliche Verwaltungseinheit 5 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    • administrative_area_level_6 gibt eine öffentliche Verwaltungseinheit 6 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    • administrative_area_level_7 gibt eine öffentliche Verwaltungseinheit 7 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
    • colloquial_area gibt eine gängige alternative Bezeichnung für die Einheit an.
    • locality gibt die politische Einheit einer Stadt oder Gemeinde an.
    • sublocality gibt eine öffentliche Verwaltungseinheit eine Stufe unterhalb des Ortes an. 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 gibt ein benanntes Stadtviertel an.
    • premise gibt einen benannten Ort an, normalerweise ein Gebäude oder einen Komplex von Gebäuden mit einem gemeinsamen Namen.
    • subpremise gibt eine erstrangige Einheit unterhalb der Ebene eines benannten Ortes an, normalerweise ein einzelnes Gebäude innerhalb eines Gebäudekomplexes mit einem gemeinsamen Namen.
    • plus_code gibt einen codierten Verweis auf den Standort an, 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 gibt eine Postleitzahl an, wie sie zum Adressieren von Postsendungen innerhalb des Landes verwendet wird.
    • natural_feature gibt ein auffallendes Landschaftsmerkmal an.
    • airport gibt einen Flughafen an.
    • park gibt einen benannten Park an.
    • point_of_interest gibt einen benannten POI an. In der Regel sind diese POIs bekannte lokale Objekte, die sich keiner anderen Kategorie zuordnen lassen, z. B. das Brandenburger Tor oder der Eiffelturm.
  • location_type (ein oder mehrere Standorttypen) durch ein Pipe-Zeichen (|) getrennt. Wenn der Parameter mehrere Standorttypen gibt die API alle Adressen zurück, die einem der Typen entsprechen. Hinweis zur Verarbeitung: Der Parameter location_type beschränkt die Suche nicht auf die angegebenen Standorttypen. location_type dient vielmehr als Filter nach der Suche: Die API ruft alle Ergebnisse für den angegebenen latlng ab und verwirft dann die Ergebnisse, die nicht mit den angegebenen Standorttypen übereinstimmen. Folgende Werte werden unterstützt:
    • "ROOFTOP" gibt nur die Adressen zurück, für die Google Standortinformationen bis hin zur Straße hat.
    • "RANGE_INTERPOLATED" gibt nur die Adressen zurück, die eine Schätzung (normalerweise auf einer Straße) sind, die anhand von zwei genauen Punkten (wie Kreuzungen) interpoliert wurde. Ein interpolierter Bereich im Allgemeinen gibt an, dass Geocodierungen für eine Adresse auf dem Dach nicht verfügbar sind.
    • "GEOMETRIC_CENTER" gibt nur geometrische Daten zurück Mittelpunkt eines Standorts, z. B. einer Polylinie (z. B. einer Straße) oder Polygon (Region) dargestellt.
    • "APPROXIMATE" gibt nur die Adressen zurück, die als annäherungsweise gekennzeichnet.
  • extra_computations: Mit diesem Parameter können Sie die folgenden zusätzlichen Funktionen in der Antwort angeben: Um mehrere dieser Funktionen für dieselbe API-Anfrage zu aktivieren, fügen Sie den Parameter extra_computations in der Anfrage für jede Funktion, Beispiel: 
    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 den location_type-Werten übereinstimmen. Ist keiner der Filterwerte akzeptabel, Die API gibt ZERO_RESULTS zurück.

Beispiel für die 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 umfassen nicht nur Postanschriften, sondern alle geografischen Bezeichnungen für einen Ort. Wenn Sie z. B. einen Punkt geocodieren in der Stadt Chicago kann der geocodierte Punkt als Adresse, als Stadt (Chicago), als ihr Bundesstaat (Illinois) oder als Land (die Bundesländer). All das wertet der Geocodierer als Adresse. Der umgekehrte Geocoder gibt als gültige Ergebnisse.

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 der spezifischen Adresse bis hin zu weniger spezifischen politischen Einheiten wie Stadtteilen, Städten, Landkreisen und Bundesländern. Je genauer die Adresse ist, desto hervorgehobenes Ergebnis, wie es hier der Fall ist. Wenn Sie eine Übereinstimmung mit einer bestimmten Art von Adresse suchen möchten, lesen Sie den Abschnitt unten zum Einschränken der Ergebnisse nach Typ. Daher wird die Position der Ergebnisse im Verhältnis zu sich gegenseitig variieren können.

Umgekehrtes Geocoding, gefiltert nach Typ

Im folgenden Beispiel werden die zurückgegebenen Adressen so gefiltert, dass nur diese enthalten sind mit dem Standorttyp ROOFTOP und dem Adresstyp street_address.

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 gelten nur für die umgekehrte Geocodierung.

Antworten für umgekehrte Geocodierung

Das Format der Antwort der umgekehrten Geocodierung entspricht dem der Geocodierungsantwort. Siehe 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 der Rückwärtsgeocoding 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, aber es wurden keine Ergebnisse zurückgegeben. Dies kann passieren, wenn der Geocoder hat ein latlng an einem entfernten Standort übergeben.
  • "OVER_QUERY_LIMIT" gibt an, dass Sie Ihr Kontingent.
  • "REQUEST_DENIED" gibt an, dass die Anfrage abgelehnt wurde. Das liegt möglicherweise daran, dass die Anfrage einen result_type- oder location_type-Parameter, enthält aber keinen API-Schlüssel.
  • "INVALID_REQUEST" steht im Allgemeinen für einen der folgenden Werte:
    • Die Abfrage (address, components oder latlng) fehlt.
    • Eine ungültige result_type oder location_type wurde gegeben ist.
  • "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 Geocodierungsantwort enthält einen Plus-Code, der dem angefragten Breiten- und Längengrad am besten entspricht. Darüber hinaus enthält das JSON-Ergebnisarray in den meisten Fällen eine vollständige Ergebnis mit dem Typ plus_code und einer Adresse, die ein Pluszeichen enthält Code. Die Entfernung zwischen dem decodierten Pluscode und dem Anfragepunkt beträgt garantiert weniger als 10 Meter.