Ort geocodieren

Entwickler im Europäischen Wirtschaftsraum (EWR)

Mit der Orts-Geocodierung können Sie eine Adresse anhand einer Orts-ID abrufen.

Mit einer Orts-ID wird ein Ort in der Google Places-Datenbank und in Google Maps eindeutig identifiziert. Orts-IDs werden abgerufen, wenn Sie eine Adresse geocodieren. Sie können eine Orts-ID auch über viele andere APIs abrufen, z. B. Place Details (New), Text Search (New) und Nearby Search (New).

Geocoding-Anfragen für Orte stellen

Eine Orts-Geocoding-Anfrage ist eine HTTP-GET-Anfrage in folgendem Format:

https://geocode.googleapis.com/v4/geocode/places/PLACE_ID

Dabei enthält PLACE_ID die Orts-ID des Orts von Interesse.

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:

https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw?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/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"

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 Ortsgeocodierung:

  • https://www.googleapis.com/auth/maps-platform.geocode – Für alle Geocoding API-Methoden verwenden.
  • https://www.googleapis.com/auth/maps-platform.geocode.place – Nur mit GeocodePlace für die Orts-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 Zugriff auf alle Methoden ermöglicht.

Weitere Informationen und Beispiele finden Sie unter OAuth verwenden.

Geocoding-Antworten für Orte

Bei der Ortsgeocodierung wird ein GeocodeResult-Objekt zurückgegeben, das den Ort darstellt, der der Orts-ID entspricht.

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)“.

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

{
  "place": "//places.googleapis.com/places/ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "placeId": "ChIJj61dQgK6j4AR4GeTYWZsKWw",
  "location": {
    "latitude": 37.4220541,
    "longitude": -122.08532419999999
  },
  "granularity": "ROOFTOP",
  "viewport": {
    "low": {
      "latitude": 37.4209489697085,
      "longitude": -122.08846930000001
    },
    "high": {
      "latitude": 37.4236469302915,
      "longitude": -122.0829156
    }
  },
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
  "postalAddress": {
    "regionCode": "US",
    "languageCode": "en",
    "postalCode": "94043",
    "administrativeArea": "CA",
    "locality": "Mountain View",
    "addressLines": [
      "1600 Amphitheatre Pkwy"
    ]
  },
  "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"
  ]
}

Erforderliche Parameter

  • place: die Orts-ID des Ortes, für den die Adresse in visuell lesbarer Form ausgegeben werden soll. Die Orts-ID ist eine eindeutige Kennung, die mit anderen Google APIs verwendet werden kann. Sie können z. B. die von der Roads API zurückgegebene placeID angeben, um die Adresse für einen bestimmten Punkt abzurufen. Weitere Informationen zu Orts-IDs finden Sie unter Orts-IDs.

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 Einheimische lesbar ist. Dazu werden Straßenadressen in der Landessprache 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. 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, wird die nächstgelegene Übereinstimmung verwendet.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnismenge, die von der API zurückgegeben wird, 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.

  • FieldMask

    Erstellen Sie eine Antwortfeldmaske, 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 wird beispielsweise nur das Feld formattedAddress der Antwort zurückgegeben.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: formattedAddress' \
-H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw"
    Die Antwort lautet: 
    {
  "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA"
}

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