Umgekehrte Geocodierung eines Standorts

Entwickler im Europäischen Wirtschaftsraum (EWR)

Bei der umgekehrten Geocodierung wird ein Kartenstandort in eine visuell lesbare Adresse umgewandelt. Sie stellen den Kartenstandort durch die Breiten- und Längengradkoordinaten des Standorts dar.

Wenn Sie einen Ort umgekehrt geocodieren, enthält die Antwort Folgendes:

Diese API gibt verschiedene Arten von Adressen zurück, von der genauen Straßenadresse bis hin zu weniger genauen politischen Einheiten wie Stadtteilen, Städten, Landkreisen und Bundesländern. Die am besten passende Adresse ist in der Regel das erste Ergebnis. Wenn Sie einen bestimmten Adresstyp abgleichen möchten, verwenden Sie den Parameter types.

Antrag auf umgekehrte Geocodierung

Eine Reverse Geocoding-Anfrage ist eine HTTP-GET-Anfrage. Sie können den Standort als unstrukturierten String angeben:

https://geocode.googleapis.com/v4/geocode/location/LATITUDE,LONGITUDE

Oder als strukturierter Satz von Breiten- und Längengradkoordinaten, die durch Abfrageparameter dargestellt werden:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=LATITUDE&location.longitude=LONGITUDE

Sie verwenden das strukturierte Format in der Regel, wenn Sie Standortkomponenten verarbeiten, die in einem HTML-Formular erfasst wurden.

Alle anderen Parameter werden als URL-Parameter oder, bei Parametern wie dem API-Schlüssel oder der Feldmaske, in Headern als Teil der GET-Anfrage übergeben. Beispiel:

Unstrukturierten Standortstring übergeben

Ein unstrukturierter Standort ist ein Standort, der als kommagetrennter String mit Breiten- und Längengradkoordinaten formatiert ist:

https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?key=API_KEY

Oder in einem curl-Befehl:

curl -X GET -H 'Content-Type: application/json' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"

Strukturierte Standortinformationen übergeben

Geben Sie den strukturierten Ort mit dem Abfrageparameter location vom Typ LatLng an. Mit dem LatLng-Objekt können Sie Breiten- und Längengrad als separate Abfrageparameter angeben:

https://geocode.googleapis.com/v4/geocode/location?location.latitude=37.4225508&location.longitude=-122.0846338&key=API_KEY

OAuth zum Stellen einer Anfrage verwenden

Die Geocoding API v4 unterstützt OAuth 2.0 für die Authentifizierung. Wenn Sie OAuth mit der Geocoding API verwenden möchten, muss dem OAuth-Token der richtige Bereich zugewiesen sein. Die Geocoding API unterstützt die folgenden Bereiche für die Verwendung mit der umgekehrten Geocodierung:

  • https://www.googleapis.com/auth/maps-platform.geocode – Kann mit allen Geocoding API-Methoden verwendet werden.
  • https://www.googleapis.com/auth/maps-platform.geocode.location – Nur mit GeocodeLocation für die umgekehrte Geocodierung verwenden.

Außerdem können Sie den allgemeinen https://www.googleapis.com/auth/cloud-platform-Bereich für alle Geocoding API-Methoden verwenden. Dieser Bereich ist während der Entwicklung nützlich, aber nicht in der Produktion, da er ein allgemeiner Bereich ist, der den Zugriff auf alle Methoden ermöglicht.

Weitere Informationen und Beispiele finden Sie unter OAuth verwenden.

Antwort auf umgekehrte Geocodierung

Bei der umgekehrten Geocodierung wird ein GeocodeLocationResponse-Objekt zurückgegeben, das Folgendes enthält:

  • Das results-Array von GeocodeResult-Objekten, das den Ort darstellt.

    Die Antworten der Geocoding API enthalten types-Arrays an zwei Hauptstellen innerhalb von GeocodeResult:

    1. GeocodeResult.types: Dieses Array gibt den/die Gesamttyp(en) des Ergebnisses an. Die möglichen Werte stammen aus Tabelle A und Tabelle B auf der Seite „Ortstypen (Neu)“.
    2. GeocodeResult.addressComponents[].types: Jede Adresskomponente hat ein types-Array, das den Typ dieses bestimmten Teils der Adresse angibt. Diese Werte stammen aus der Tabelle Typen von Adressen und Adresskomponenten auf der Seite „Ortstypen (neu)“.

    Bei der umgekehrten Geocodierung wird mehr als ein Ergebnis im results-Array zurückgegeben. Die 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. Alle diese Angaben gelten im Geocoder als Adressen. Bei der umgekehrten Geocodierung werden alle genannten Typen als gültige Ergebnisse zurückgegeben.

  • Das Feld plusCode vom Typ PlusCode enthält den Plus Code, der den Breiten- und Längengrad in der Anfrage am besten annähert. Außerdem enthält jedes Element des results-Arrays einen Plus Code. Die Entfernung zwischen dem decodierten Plus Code und dem Anfragepunkt beträgt weniger als 10 Meter.

    Hinweis: Die API gibt nicht immer Plus Codes zurück.

Das vollständige JSON-Objekt hat das folgende Format:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "placeId": "ChIJV-FZF7i7j4ARo4ZOUoecZFU",
      "location": {
        "latitude": 37.422588300000008,
        "longitude": -122.0846489
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.421239319708512,
          "longitude": -122.0859978802915
        },
        "high": {
          "latitude": 37.423937280291511,
          "longitude": -122.08329991970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCW83+PM",
        "compoundCode": "CW83+PM Mountain View, CA, USA"
      }
    },
    {
      "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
      "location": {
        "latitude": 37.4220541,
        "longitude": -122.08532419999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.4207051197085,
          "longitude": -122.08667318029148
        },
        "high": {
          "latitude": 37.423403080291493,
          "longitude": -122.08397521970851
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Mountain View",
          "shortText": "Mountain View",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "Santa Clara County",
          "shortText": "Santa Clara County",
          "types": [
            "administrative_area_level_2",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "California",
          "shortText": "CA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "United States",
          "shortText": "US",
          "types": [
            "country",
            "political"
          ],
          "languageCode": "en"
        },
        {
          "longText": "94043",
          "shortText": "94043",
          "types": [
            "postal_code"
          ]
        }
      ],
      "types": [
        "establishment",
        "point_of_interest"
      ],
      "plusCode": {
        "globalCode": "849VCWC7+RV",
        "compoundCode": "CWC7+RV Mountain View, CA, USA"
      }
    },
   ...
  ],
  "plusCode": {
    "globalCode": "849VCWF8+24H",
    "compoundCode": "CWF8+24H Mountain View, CA, USA"
  }
}

Erforderliche Parameter

  • Standort

    Die Breiten- und Längengradkoordinaten, die angeben, wo die am nächsten liegende Adresse in visuell lesbarer Form ausgegeben werden soll.

Optionale Parameter

  • languageCode

    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 languageCode nicht angegeben ist, wird standardmäßig en verwendet. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück.
    • Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Ortsansässige lesbar ist. Dazu 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.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die von der API zurückgegeben werden, und auf 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.

  • regionCode

    Der Regionscode als zweistelliger CLDR-Code. Es gibt keinen Standardwert. Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch.

    Beim Geocoding einer Adresse (Forward Geocoding) kann dieser Parameter die Ergebnisse des Dienstes für die angegebene Region beeinflussen, aber nicht vollständig einschränken. Wenn Sie einen Ort oder einen Standort geocodieren (umgekehrte Geocodierung oder Orts-Geocodierung), kann dieser Parameter verwendet werden, um die Adresse zu formatieren. In allen Fällen kann sich dieser Parameter aufgrund des anwendbaren Rechts auf die Ergebnisse auswirken.

  • Detaillierungsgrad

    Eine oder mehrere Standortgranularitäten, die als separate Abfrageparameter angegeben werden, wie in Granularity definiert. Wenn Sie mehrere granularity-Parameter angeben, gibt die API alle Adressen zurück, die mit einer der Granularitäten übereinstimmen.

    Mit dem Parameter granularity wird die Suche nicht auf die angegebenen Standorte eingeschränkt. Stattdessen dient granularity als Filter nach der Suche. Die API ruft alle Ergebnisse für die angegebene location ab und verwirft dann die Ergebnisse, die nicht den angegebenen Standortgranularitäten entsprechen.

    Wenn Sie sowohl types als auch granularity angeben, gibt die API nur Ergebnisse zurück, die beiden entsprechen. Beispiel:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?granularity=ROOFTOP&granularity=GEOMETRIC_CENTER&key=API_KEY

  • Typen

    Ein oder mehrere Adresstypen, die als separate Abfrageparameter angegeben werden. Die möglichen Werte stammen aus der Tabelle Typen von Adressen und Adresskomponenten auf der Seite „Ortstypen (neu)“. Wenn Sie mehrere types-Parameter angeben, gibt die API alle Adressen zurück, die mit einem der Typen übereinstimmen.

    Der Parameter types beschränkt die Suche nicht auf die angegebenen Adresstypen. Stattdessen dient types als Filter nach der Suche. Die API ruft alle Ergebnisse für den angegebenen Ort ab und verwirft dann die Ergebnisse, die nicht dem angegebenen Adresstyp bzw. den angegebenen Adresstypen entsprechen.

    Wenn Sie sowohl types als auch granularity angeben, gibt die API nur Ergebnisse zurück, die beiden entsprechen. Beispiel:

    https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338?types=administrative_area_level_2&types=locality&key=API_KEY

  • FieldMask

    Erstellen Sie eine Feldmaske für die Antwort, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen. Übergeben Sie die Maske für das Antwortfeld an die Methode, indem Sie den URL-Parameter $fields oder fields oder den HTTP-Header X-Goog-FieldMask verwenden. Mit der folgenden Anfrage werden beispielsweise nur die placeID-Felder der Antwort zurückgegeben.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/location/37.4225508,-122.0846338"
    Die Antwort lautet: 
    {
  "results": [
    {
      "placeId": "ChIJHRNUiQK6j4ARJ__Hrbt6qsE"
    },
    {
      "placeId": "ChIJj38IfwK6j4ARNcyPDnEGa9g"
    },
    {
      "placeId": "ChIJ1yjFJ1-7j4ARG_RVqFD1h7k"
    },
    {
      "placeId": "ChIJ09H2YwK6j4ARoF7qfCBxhB8"
    },
    ...
  ]
}

    Weitere Informationen finden Sie unter Zurückzugebende Felder auswählen.