Ort geocodieren

Entwickler im Europäischen Wirtschaftsraum (EWR)

Mit der Ortsgeocodierung können Sie eine Adresse aus einer Orts ID abrufen.

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

Anfragen zur Ortsgeocodierung

Eine Anfrage zur Ortsgeocodierung ist eine HTTP-GET-Anfrage im folgenden Format: 

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

Dabei enthält PLACE_ID die Orts-ID des gewünschten Ortes.

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

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"

Anfrage mit OAuth senden

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 Methoden der Geocoding API verwenden.
  • https://www.googleapis.com/auth/maps-platform.geocode.place : Nur mit GeocodePlace für die Ortsgeocodierung verwenden.

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.

Antworten zur Ortsgeocodierung

Die Ortsgeocodierung gibt ein GeocodeResult Objekt zurück, das den Ort darstellt, der der Orts-ID entspricht.

Die Antworten der Geocoding API enthalten types Arrays an zwei Hauptstellen in den 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 (New).
  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 (New).

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 Sie die Adresse in visuell lesbarer Form abrufen möchten. Die Orts-ID ist eine eindeutige Kennung, die mit anderen Google APIs verwendet werden kann. Sie können beispielsweise die von der Roads API zurückgegebene placeID verwenden, 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 Daher ist diese Liste möglicherweise nicht vollständig.
    • Wenn languageCode nicht angegeben wird, verwendet die API standardmäßig en. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API den 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 und bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert, wobei die bevorzugte Sprache berücksichtigt wird. 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ächstbeste Übereinstimmung.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die die API zurückgibt, und auf 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 sein können, in einer anderen jedoch nicht.

  • regionCode

    Der Regionscode als CLDR-Code mit zwei Zeichen. Es gibt keinen Standardwert. Die meisten CLDR-Codes entsprechen den ISO 3166-1-Codes.

    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 Ortes oder eines Ortes (Reverse Geocoding oder Ortsgeocodierung) kann dieser Parameter verwendet werden, um die Adresse zu formatieren. In allen Fällen kann dieser Parameter die Ergebnisse aufgrund geltenden Rechts beeinflussen.

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