Umgekehrte Geocodierung eines Standorts

Entwickler im Europäischen Wirtschaftsraum (EWR)

Bei der umgekehrten Geocodierung wird ein Standort auf einer Karte in eine Adresse in visuell lesbarer Form umgewandelt. Sie geben den Standort auf der Karte mit den Breiten- und Längengradkoordinaten des Standorts an.

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

Diese API gibt verschiedene Arten von Adressen zurück, von der genauesten Straßenadresse bis hin zu weniger genauen politischen Einheiten wie Stadtteilen, Städten, Landkreisen und Bundesländern. Die genaueste Adresse ist in der Regel das erste Ergebnis. Wenn Sie eine bestimmte Art von Adresse erhalten möchten, verwenden Sie den types Parameter.

Anfrage zur umgekehrten Geocodierung

Eine Anfrage zur umgekehrten Geocodierung ist eine HTTP-GET-Anfrage. Sie können den Standort als einen unstrukturierten String angeben:

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

Oder als eine strukturierte Menge von Breiten- und Längengrad koordinaten, die durch Abfrageparameter dargestellt werden:

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

Das strukturierte Format wird in der Regel verwendet, wenn Standortkomponenten verarbeitet werden, die in einem HTML-Formular erfasst wurden.

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

Unstrukturierten Standortstring übergeben

Ein unstrukturierter Standort ist ein Standort, der als durch Kommas getrennter 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"

Strukturierten Standort übergeben

Geben Sie den strukturierten Standort mit dem location Abfrageparameter vom Typ LatLng an. Mit dem Objekt LatLng können Sie den 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

Anfrage mit OAuth stellen

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 Methoden der Geocoding API verwendet werden.
  • https://www.googleapis.com/auth/maps-platform.geocode.location : Kann nur mit GeocodeLocation für die umgekehrte Geocodierung verwendet werden.

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

Weitere Informationen und Beispiele finden Sie unter OAuth verwenden.

Antwort zur umgekehrten 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 in den GeocodeResult:

    1. GeocodeResult.types: Dieses Array gibt den/die allgemeinen Typ(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 Adresstypen und Adresskomponententypen auf der Seite Ortstypen (neu).

    Bei der umgekehrten Geocodierung werden im Array results mehrere Ergebnisse 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 diese 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 Sie die nächstgelegene, visuell lesbare Adresse erhalten möchten.

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 sodass diese Liste unter Umständen nicht vollständig ist.
    • Wenn languageCode nicht angegeben ist, verwendet die API standardmäßig en. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API einen INVALID_ARGUMENT Fehler zurück.
    • Die API versucht, eine Straßenadresse bereitzustellen, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Zu diesem Zweck werden Straßen adressen in der lokalen Sprache zurückgegeben, bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert und die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand 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 Menge der 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.

    Bei der Geocodierung einer Adresse (Forward Geocoding) kann dieser Parameter die Ergebnisse des Dienstes für die angegebene Region beeinflussen, aber nicht vollständig einschränken. Bei der Geocodierung eines Standorts oder eines Ortes (umgekehrte Geocodierung oder Orts-Geocodierung) kann dieser Parameter verwendet werden, um die Adresse zu formatieren. In allen Fällen kann dieser Parameter die Ergebnisse auf Grundlage des geltenden Rechts beeinflussen.

  • Leseeinheit

    Eine oder mehrere Standortdetaillierungsgrade, die als separate Suchparameter angegeben werden, wie in Granularity definiert. Wenn Sie mehrere granularity-Parameter angeben, gibt die API alle Adressen zurück, die mit einer der Leseeinheiten übereinstimmen.

    Der granularity Parameter schränkt die Suche nicht auf die angegebenen Standortleseeinheiten ein. Stattdessen, granularity dient als Filter nach der Suche. Die API ruft alle Ergebnisse für den angegebenen location ab und verwirft dann die Ergebnisse, die nicht mit den angegebenen Standortleseeinheiten übereinstimmen.

    Wenn Sie sowohl types als auch granularity angeben, gibt die API nur die Ergebnisse zurück, die mit beiden übereinstimmen. 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 Adresstypen und Adresskomponententypen 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 types Parameter schränkt die Suche nicht auf die angegebenen Adresstypen ein. Stattdessen types dient als Filter nach der Suche. Die API ruft alle Ergebnisse für den angegebenen Standort ab und verwirft dann die Ergebnisse, die nicht mit den angegebenen Adresstypen übereinstimmen.

    Wenn Sie sowohl types als auch granularity angeben, gibt die API nur die Ergebnisse zurück, die mit beiden übereinstimmen. 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 Feldmaske für die Antwort an die Methode, indem Sie den URL-Parameter $fields oder fields, oder indem Sie den HTTP-Header X-Goog-FieldMask verwenden. Die folgende Anfrage gibt beispielsweise nur die Felder placeID der Antwort zurück.

    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.