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
- Zu aktivierender Dienst:
geocoding-backend.googleapis.com - Authentifizierung: API-Schlüssel, OAuth 2.0, Dienstkonto
- Erste Schritte: Geocoding API einrichten
- Referenz: Geocoding API-Referenz
- Preise: Geocoding API-Nutzung und -Abrechnung
- Richtlinien: Geocoding API-Richtlinien
- Versionshinweise: Versionshinweise zur Geocoding API
Geocoding API: ähnliche Produkte
- Häufig verwendet mit: Routes API, Navigation SDK for Android, Navigation SDK for iOS
Geocoding API: Häufige Fehler
- Problem:
SearchDestinations-Anfragen ohne Feldmaske schlagen mit einem Fehler fehl. Im Gegensatz zuGeocodeAddress,GeocodeLocationundGeocodePlaceist die Feldmaske erforderlich. Lösung: Legen Sie den HeaderX-Goog-FieldMaskoder den Parameter$fieldsfür jedeSearchDestinations-Anfrage fest. Weitere Informationen finden Sie unter /maps/documentation/geocoding/choose-fields. - Problem: In v4 von
GeocodeAddressgibt es keinen harten Komponentenfilter (v3components=country:US). Strukturierteaddress.*-Parameter werden zu einer Adresse zusammengefasst und filtern die Ergebnisse nicht. Außerdem gibt es in v4 keinen Standardwert fürregionCode(in v3 war der Standardwertus). Lösung: Filtern Sieresultsclientseitig: Gleichen SieregionCodein Großbuchstaben mitpostalAddress.regionCodeab. Gleichen Sie zweistellige Verwaltungsgebiete in Großbuchstaben mitpostalAddress.administrativeAreaundadministrative_area_level_naddressComponents(shortText) ab. Normalisieren Sie sowohl die Eingabe als auchpostalAddress.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:
SearchDestinationskann im Gegensatz zu v3 und den anderen v4-Methoden Ergebnisse ohne genaue primäre Adresse zurückgeben. Lösung: Setzen SieplaceFilter.addressabilityaufPRIMARY, 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, nichtaddress_components),statusunderror_messagewerden entfernt und es wird ein einzelnes Stammobjekt vonGeocodePlaceanstelle einesresults-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; Antwortfelderbuildings.entrances,navigation_points,buildings.building_outlines,grounds): Eingestellt seit dem 13.08.2025. Ersatz: Geocoding API v4-MethodeSearchDestinations(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.
- Breiten- und Längengradkoordinaten einer Adresse zurückgeben (Geocoding)
- Adresse für einen Satz von Breiten- und Längengradkoordinaten zurückgeben (umgekehrte Geocodierung)
- Geocoding-Anfragen so einschränken, dass nur Ergebnisse innerhalb eines bestimmten Darstellungsbereichs zurückgegeben werden Hinweis: In der Geocoding API v4 werden die Ergebnisse mit „locationBias“ auf den angegebenen Darstellungsbereich ausgerichtet, anstatt sie strikt einzuschränken.
- Geocodierungs- oder umgekehrte Geocodierungsanfragen so einschränken, dass nur Ergebnisse innerhalb einer bestimmten Region, eines bestimmten Landes oder einer bestimmten Postleitzahl zurückgegeben werden Hinweis: In der Geocoding API v4 werden die Ergebnisse durch „regionCode“ auf eine bestimmte CLDR-Region ausgerichtet, anstatt sie strikt einzuschränken. Informationen zur Komponentenfilterung nach Land oder Postleitzahl in der alten Version 3 finden Sie unter https://developers.google.com/maps/documentation/geocoding/guides-v3/requests-geocoding#ComponentFiltering.
- Anfragen zur umgekehrten Geocodierung so einschränken, dass nur Ergebnisse für bestimmte Adresstypen zurückgegeben werden Hinweis: In der Geocoding API v4 werden die zurückgegebenen Ergebnisse der umgekehrten Geocodierung nach der Suche mit dem Parameter „types“ nach Adresstyp gefiltert, anstatt die zugrunde liegende Suche einzuschränken.
- Informationen zur Nähe zu Sehenswürdigkeiten oder Gebieten für eine Adresse zurückgeben
- Informationen zur Nähe zu Sehenswürdigkeiten oder Gebieten für eine Reihe von Breiten- und Längengradkoordinaten zurückgeben
- Informationen zur Nähe zu Sehenswürdigkeiten oder Gebieten für eine Google-Orts-ID zurückgeben
- Adresse für eine Google-Orts-ID zurückgeben
- Breiten- und Längengradkoordinaten eines Gebäudeumrisses für eine Adresse zurückgeben
- Breiten- und Längengradkoordinaten eines Gebäudeumrisses für eine Reihe von Breiten- und Längengradkoordinaten zurückgeben
- Breiten- und Längengradkoordinaten eines Gebäudeumrisses für eine Google-Orts-ID zurückgeben
- Breiten- und Längengradkoordinaten des Gebäudeeingangs für eine Adresse zurückgeben
- Breiten- und Längengradkoordinaten eines Gebäudeeingangs für eine Reihe von Breiten- und Längengradkoordinaten zurückgeben
- Breiten- und Längengradkoordinaten eines Gebäudeeingangs für eine Google-Orts-ID zurückgeben