Adressen geocodieren

Beim Geocoding wird eine Adresse in einen Standort auf einer Karte umgewandelt. Wenn Sie eine Adresse geocodieren, enthält die Antwort Folgendes:

• Orts-ID des Standorts
• Breiten- und Längengradkoordinaten des Standorts
• Plus Code des Orts
• Erweiterte Adressdetails

Geocoding-Anfrage

Eine Geocode-Anfrage ist eine HTTP-GET-Anfrage. Sie können die Adresse als unstrukturierten String angeben:

https://geocode.googleapis.com/v4beta/geocode/address/ADDRESS_STRING

Oder als strukturierte Gruppe von Adresskomponenten, die durch Abfrageparameter dargestellt werden:

https://geocode.googleapis.com/v4beta/geocode/address?STRUCTURED_ADDRESS

Normalerweise verwenden Sie das strukturierte Format, wenn Sie Adresskomponenten verarbeiten, die in einem HTML-Formular erfasst wurden.

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

Unstrukturierten Adressstring übergeben

Eine unstrukturierte Adresse ist eine Adresse, die als String oder Plus Code formatiert ist. Im folgenden Beispiel wird die URL-codierte Adresszeichenfolge „1600 Amphitheatre Parkway, Mountain View, CA“ übergeben:

https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Das Zeichen „+“ in der URL wird in ein Leerzeichen umgewandelt.

Sie können die Anfrage auch mit einem curl-Befehl stellen:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4beta/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Adressen können viele Arten von Sonderzeichen enthalten. Beispiel: „/“ wie in „7/1 King St, Concord West“. Codieren Sie „/“ als %2F:

https://geocode.googleapis.com/v4beta/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Ein weiteres häufiges Beispiel ist das Zeichen „#“, wie in „9500 W Bryn Mawr Ave #650, Rosemont“. Codieren Sie das „#“ als %2FE:

https://geocode.googleapis.com/v4beta/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Im nächsten Beispiel geben Sie einen unstrukturierten Adressstring als Plus-Code 849VCWC8+R4 an. Achten Sie darauf, dass Sie das Zeichen „+“ als %2B URL-codieren:

https://geocode.googleapis.com/v4beta/geocode/address/849VCWC8%2BR4?key=API_KEY

Strukturierte Adresse übergeben

Geben Sie eine strukturierte Adresse mit dem Abfrageparameter address vom Typ PostalAddress an. Mit dem PostalAddress-Objekt können Sie einige oder alle Adresskomponenten in der Anfrage als einzelne Abfrageparameter angeben.

Wenn Sie beispielsweise nur die Postleitzahl der Adresse angeben möchten, verwenden Sie PostalAddress.postalCode:

https://geocode.googleapis.com/v4beta/geocode/address?address.postalCode=01062&key=API_KEY

Wenn Sie mehrere Adresskomponenten angeben möchten, z. B. für Adresskomponenten, die in einem HTML-Formular erfasst werden, verwenden Sie mehrere Abfrageparameter:

https://geocode.googleapis.com/v4beta/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&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 Geocodierung:

• https://www.googleapis.com/auth/maps-platform.geocode – Mit allen Geocoding API-Endpunkten verwenden.
• https://www.googleapis.com/auth/maps-platform.geocode.address – Nur mit GeocodeAddress für die Vorwärtsgeocodierung verwenden.

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

Weitere Informationen und Beispiele finden Sie unter OAuth verwenden.

Geocode-Antwort

Beim Geocoding wird ein GeocodeAddressResponse-Objekt zurückgegeben, das das results-Array von GeocodeResult-Objekten enthält. Jedes GeocodeResult-Objekt stellt einen einzelnen Ort dar.

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

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "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"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Erforderliche Parameter

• address: die Adresse oder der Plus Code, die bzw. den Sie geocodieren möchten. Geben Sie Adressen in dem Format an, das vom Postdienst des entsprechenden Landes verwendet wird. Zusätzliche Adresselemente wie Firmennamen und Wohnungs-, Büro- oder Etagennummern sollten vermieden werden. Die Elemente der Adresse sollten durch Leerzeichen getrennt und URL-codiert sein (%20). Übergeben Sie beispielsweise die Adresse „24 Sussex Drive Ottawa ON“ so:

  24%20Sussex%20Drive%20Ottawa%20ON

  Formatieren Sie Plus Codes wie unten gezeigt. Pluszeichen werden in der URL als %2B dargestellt, Leerzeichen als %20:
  • Ein Global Code besteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code. Codieren Sie beispielsweise „849VCWC8+R9“ als 849VCWC8%2BR9.
  • Ein Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort. Codieren Sie beispielsweise „CWC8+R9 Mountain View, CA, USA“ als CWC8%2BR9%20Mountain%20View%20CA%20USA.

Optionale Parameter

• locationBias

  Gibt einen Bereich für die Suche als Viewport an. Dieser Ort dient als Gewichtung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Ortes zurückgegeben werden können, auch wenn sie sich nicht im angegebenen Bereich befinden.

  Geben Sie die Region als rechteckigen Darstellungsbereich an. Ein Rechteck ist ein Darstellungsbereich für Breiten- und Längengrade, der durch zwei diagonal gegenüberliegende niedrige und hohe Punkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der Hochpunkt die nordöstliche Ecke.

  Ein Darstellungsbereich gilt als geschlossener Bereich, d. h., er umfasst auch seine Grenze. Die Grenzen für den Breitengrad müssen zwischen -90 und 90 Grad liegen (einschließlich), und die Grenzen für den Längengrad müssen zwischen -180 und 180 Grad liegen (einschließlich):

  • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
  • Wenn low.longitude > high.longitude, wird der Längengradbereich umgekehrt (der Darstellungsbereich überschreitet die 180-Grad-Längengradlinie).
  • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, umfasst der Darstellungsbereich alle Längengrade.
  • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad ist, ist der Längengradbereich leer.
  • Wenn low.latitude > high.latitude, ist der Breitengradbereich leer.

  Sowohl „Niedrig“ als auch „Hoch“ müssen ausgefüllt sein und das dargestellte Rechteck darf nicht leer sein. Ein leerer Viewport führt zu einem Fehler.

  Mit diesem Abfragestring wird beispielsweise ein Viewport definiert, der New York City vollständig umschließt:

  ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

• 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, verwendet die API standardmäßig en. 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 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. 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.

Standortgewichtung

Mit dem locationBias-Parameter können Sie den Geocoding-Dienst so einrichten, dass Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) bevorzugt werden. Der Parameter locationBias definiert die Breiten- und Längengradkoordinaten der Südwest- und Nordostecke dieses Begrenzungsrahmens.

Bei einer Geocoding-Anfrage für die Adresse „Washington“ können beispielsweise Ergebnisse für Washington, D.C. und für den US-Bundesstaat Washington zurückgegeben werden:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?key=API_KEY

Die Antwort hat folgendes Format:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Wenn jedoch ein locationBias-Parameter hinzugefügt wird, der einen Begrenzungsrahmen für den Nordosten der USA definiert, wird als Ergebnis des Geocodings nur die Stadt Washington, D.C. zurückgegeben:

https://geocode.googleapis.com/v4beta/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Regionsgewichtung

In einer Geocoding-Anfrage können Sie den Geocoding-Dienst mit dem Parameter regionCode anweisen, Ergebnisse zurückzugeben, die nach einer bestimmten Region gewichtet sind. Dieser Parameter akzeptiert einen zweistelligen CLDR-Code, der die regionale Gewichtung angibt. Die meisten CLDR-Codes sind mit ISO 3166-1-Codes identisch.

Es gibt keinen Standardwert für regionCode. Bei der Geocodierung von „Toledo“ erhalten Sie z. B. Ergebnisse für die USA und für Spanien:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?key=API_KEY

Response:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Bei einer Geocodierungsanfrage für „Toledo“ mit regionCode=es (Spanien) werden nur Ergebnisse aus Spanien zurückgegeben:

https://geocode.googleapis.com/v4beta/geocode/address/Toledo?regionCode=es&key=API_KEY