Umgekehrte Geocodierung eines Standorts

Entwickler im Europäischen Wirtschaftsraum (EWR)

Bei der umgekehrten Geocodierung wird ein Standort auf einer Karte in eine menschenlesbare Adresse umgewandelt. Der Standort auf der Karte wird durch die Breiten- und Längengradkoordinaten des Standorts dargestellt.

Wenn Sie eine umgekehrte Geocodierung für einen Ort durchführen, enthält die Antwort Folgendes:

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. Die am besten passende Adresse wird normalerweise an erster Stelle angezeigt. Wenn Sie einen bestimmten Adresstyp abgleichen möchten, verwenden Sie den Parameter types.

Anfrage zur umgekehrten Geocodierung

Eine Anfrage zur umgekehrten Geocodierung 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 Suchparameter 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 kommagetrennter String aus 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 Suchparameter location vom Typ LatLng an. Mit dem LatLng-Objekt können Sie den Breiten- und Längengrad als separate Suchparameter 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 – Wird mit allen Geocoding API-Methoden verwendet.
  • 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 es sich um einen allgemeinen Bereich handelt, der Zugriff auf alle Methoden ermöglicht.

Weitere Informationen und Beispiele finden Sie unter OAuth verwenden.

Antwort der umgekehrten Geocodierung

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

  • Das results-Array von GeocodeResult-Objekten, die den Ort darstellen.

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

    1. GeocodeResult.types: Dieses Array gibt den allgemeinen Typ des Ergebnisses an. Die möglichen Werte stammen aus den von der Places API verwendeten Ortstypen. Weitere Informationen finden Sie unter Ortstypen in Tabelle A und B.
    2. GeocodeResult.addressComponents[].types: Jede Adresskomponente hat ein types-Array, das den Typ des jeweiligen Adressbestandteils angibt. Diese Werte stammen aus der Tabelle Typen von Adressen und Adresskomponenten, die von der Places API verwendet wird.

    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 diese Typen als gültige Ergebnisse zurückgegeben.

  • Das Feld plusCode vom Typ PlusCode enthält den Plus Code, der dem Breiten- und Längengrad in der Anfrage am besten entspricht. 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 folgendes 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, menschenlesbare 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 die lokale Sprache und Schrift des Standorts. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den Fehler INVALID_ARGUMENT zurück.
    • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Adressen in der Landessprache zurückgegeben, die bei Bedarf in eine für den Nutzer lesbare Schrift transkribiert werden. Dabei wird die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die von 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 von der API zurückgegebenen Ergebnisse und die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sind, 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 (Geocodierung) kann dieser Parameter die Ergebnisse des Dienstes beeinflussen, aber nicht vollständig auf die angegebene Region beschränken. Wenn Sie einen Ort oder eine Adresse geocodieren, umgekehrt geocodieren oder geocodieren, können Sie mit diesem Parameter die Adresse formatieren. In allen Fällen kann dieser Parameter die Ergebnisse gemäß geltendem Recht beeinflussen.

  • Detaillierungsgrad

    Eine oder mehrere Ortsgranularitäten, die als separate Suchparameter angegeben werden, wie durch Granularity definiert. Wenn Sie mehrere granularity-Parameter angeben, gibt die API alle Adressen zurück, die einer der Granularitäten entsprechen.

    Der Parameter granularity beschränkt die Suche nicht auf die angegebenen Standortgranularitäten. Vielmehr fungiert 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 Ortsgranularitäten entsprechen.

    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 Suchparameter 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.

    Mit dem Parameter types wird die Suche nicht auf die angegebenen Adresstypen beschränkt. Vielmehr fungiert types als Filter nach der Suche. Die API ruft alle Ergebnisse für den angegebenen Ort 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 Antwortfeldmaske, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen. Übergeben Sie die Antwortfeldmaske mit dem URL-Parameter $fields oder fields oder mit dem HTTP-Header X-Goog-FieldMask an die Methode. 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 Felder für die Rückgabe auswählen.