Geocoding API – Kurzübersicht

Die Geocoding API ist ein Webdienst, mit dem Adressen in Koordinaten und Orts-IDs sowie Koordinaten oder Orts-IDs in Adressen umgewandelt werden können. Die v4-Methode SearchDestinations gibt auch Zieldetails wie Gebäudeeingänge, Navigationspunkte, Gebäude- und Grundstücksumrisse sowie nahe gelegene Orientierungspunkte zurück.

Geocoding API: Wichtige Fakten

  • Produkt: Geocoding API
  • Kategorie: Orte
  • Plattform: Webdienst (REST)
  • Ausführung auf: Server (Backend-Code)
  • Einführungsphase: GA
  • Lebenszyklus: Aktiv
  • Übersicht: Geocoding API – Übersicht

Geocoding API: Wann sollte sie verwendet werden?

Verwenden Sie die Geocoding API, wenn:

  • Sie müssen eine Adresse in Breiten- und Längengradkoordinaten und eine Orts-ID auf Ihrem Backend-Server umwandeln.
  • Für GPS-Koordinaten oder eine bekannte Orts-ID benötigen Sie eine angezeigte Adresse oder ein Verwaltungsgebiet (Stadt, Postleitzahl).
  • Sie benötigen Gebäudeeingänge, routingfähige Navigationspunkte oder Gebäude-/Geländeumrisse, um Fahrer oder Kuriere zu einem Ziel zu leiten.
  • Sie müssen ein Ziel innerhalb eines großen Komplexes (Flughafen, Einkaufszentrum, Campus) in Unterziele oder nahe gelegene Sehenswürdigkeiten auflösen.

Verwenden Sie die Geocoding API nicht, wenn:

  • Sie benötigen Geocoding über clientseitiges Browser-JavaScript. Der Aufruf von v4 mit einem offengelegten API-Schlüssel ist ein Sicherheitsrisiko. Verwenden Sie stattdessen die Maps JavaScript API.
  • Sie müssen eine Route oder voraussichtliche Ankunftszeit zum geocodierten Ziel berechnen. Verwenden Sie stattdessen die Routes API.
  • Sie benötigen eine detaillierte Routenführung zu einem Navigationspunkt-Token in einer Android-App. Verwenden Sie stattdessen das Navigation SDK for Android.
  • Sie benötigen eine detaillierte Routenführung zu einem Navigationspunkt-Token in einer iOS-App. Verwenden Sie stattdessen das Navigation SDK for iOS.

Geocoding API: Einrichtung

Geocoding API: Häufige Fehler

  • Problem: SearchDestinations-Anfragen ohne Feldmaske schlagen mit einem Fehler fehl. Im Gegensatz zu GeocodeAddress, GeocodeLocation und GeocodePlace ist die Feldmaske erforderlich. Lösung: Legen Sie den Header X-Goog-FieldMask oder den Parameter $fields für jede SearchDestinations-Anfrage fest. Weitere Informationen finden Sie unter /maps/documentation/geocoding/choose-fields.
  • Problem: In v4 von GeocodeAddress gibt es keinen harten Komponentenfilter (v3 components=country:US). Strukturierte address.*-Parameter werden zu einer Adresse zusammengefasst und filtern die Ergebnisse nicht. Außerdem gibt es in v4 keinen Standardwert für regionCode (in v3 war der Standardwert us). Lösung: Filtern Sie results clientseitig: Gleichen Sie regionCode in Großbuchstaben mit postalAddress.regionCode ab. Gleichen Sie zweistellige Verwaltungsgebiete in Großbuchstaben mit postalAddress.administrativeArea und administrative_area_level_n addressComponents (shortText) ab. Normalisieren Sie sowohl die Eingabe als auch postalAddress.postalCode (Leerzeichen/Bindestriche entfernen und Regionsregeln anwenden). Weitere Informationen finden Sie unter /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problem: Wenn die Geocoding API v4 direkt über JavaScript im Browser aufgerufen wird, wird der API-Schlüssel offengelegt. Einschränkungen für HTTP-Referrer können umgangen werden, indem der Referer-Header gefälscht wird. Lösung: Rufen Sie v4 von Ihrem eigenen Backend mit einem geschützten Schlüssel auf oder verwenden Sie den Geocoding-Dienst der Maps JavaScript API (v3-Backend) für clientseitige Anforderungen. Weitere Informationen finden Sie unter /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problem: SearchDestinations kann im Gegensatz zu v3 und den anderen v4-Methoden Ergebnisse ohne genaue primäre Adresse zurückgeben. Lösung: Setzen Sie placeFilter.addressability auf PRIMARY, wenn Sie nur Ergebnisse mit genauen Primäradressen benötigen. Weitere Informationen finden Sie unter /maps/documentation/geocoding/geocoding-v4-migrate.
  • Problem: Code, der für die Geocoding API v3 geschrieben wurde, funktioniert bei REST-Antworten der Version 4 nicht. In Version 4 werden Feldnamen in lowerCamelCase verwendet (addressComponents, nicht address_components), status und error_message werden entfernt und es wird ein einzelnes Stammobjekt von GeocodePlace anstelle eines results-Arrays zurückgegeben. Fehlerbehebung: Prüfen Sie die HTTP-Statuscodes und Fehlertexte bei v4-REST-Aufrufen, lesen Sie die Felder im lowerCamelCase-Format (addressComponents, postalAddress) und beachten Sie, dass gRPC-Antworten weiterhin das snake_case-Format verwenden. Weitere Informationen finden Sie unter /maps/documentation/geocoding/geocoding-v4-migrate.

Geocoding API: Legacy- und verworfene Funktionen

  • Hyperlokale Daten der Geocoding API v3 (extra_computations: BUILDING_AND_ENTRANCES, NAVIGATION_POINTS, GROUNDS; Antwortfelder buildings.entrances, navigation_points, buildings.building_outlines, grounds): Eingestellt seit dem 13.08.2025. Ersatz: Geocoding API v4-Methode SearchDestinations (POST /v4/geocode/destinations). Weitere Informationen finden Sie in der Migrationsanleitung.

Möglichkeiten mit der Geocoding API

In den unten verlinkten Anleitungen finden Sie Informationen zu den einzelnen Aufgaben. Sie können die Produkte auch im Capabilities Explorer vergleichen.