Von Geocoding v3 zu v4 migrieren

Entwickler im Europäischen Wirtschaftsraum (EWR)

Wenn sich Ihre Rechnungsadresse im Europäischen Wirtschaftsraum befindet, unterliegt Ihre Nutzung der Dienste ab dem 8. Juli 2025 den Nutzungsbedingungen der Google Maps Platform für den EWR. Die Funktionalität variiert je nach Region. Weitere Informationen

In der Geocoding API v4 werden mehrere neue Endpunkte eingeführt, die Funktionen aus der Version 3 der API ersetzen. In diesem Leitfaden erfahren Sie, wie Sie Ihre App so migrieren, dass die neuen v4-Endpunkte verwendet werden.

Sie können Ihre vorhandenen API-Schlüssel mit den neuen v4-Endpunkten verwenden. Wenn Sie jedoch eine Kontingenterhöhung für Version 3 der API beantragt haben, müssen Sie eine Erhöhung für die neuen APIs der Version 4 beantragen. Für JavaScript-Nutzer gibt es keinen Migrationspfad.

Hinweis:Während der Vorschauphase sind die Methoden der Geocoding API v4 auf 25 Abfragen pro Sekunde (Queries per Second, QPS) begrenzt. Informationen zum Anfordern eines höheren Kontingents finden Sie unter Kontingente ansehen und verwalten. Wählen Sie dort Geocoding API als Dienst aus.

Von v3 Forward Geocoding migrieren

Wenn Sie Geocoding zum Geocodieren von Adressen verwenden, sollten Sie zum v4-Endpunkt Geocode an address (Adresse geocodieren) migrieren, der eine GET-Anfrage akzeptiert.

In der Version 4 der API wurden Namen, Struktur und Unterstützung für mehrere Parameter geändert. Wir empfehlen dringend, eine Feldmaske zu verwenden, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen.

Warnung :In allen v4-Endpunkten werden Feldnamen im Lower Camel Case formatiert (z. B. „addressComponents“). In v3-Endpunkten wurde dagegen die Snake-Case-Schreibweise verwendet (z. B. „address_components“). In Version 4 wird für RPC-Antworten weiterhin Snake Case verwendet, wie in Version 3.

Änderungen an Anfrageparametern

v3-Parameter	v4-Parameter	Hinweise
address, components	address	Die unstrukturierte Adresse (v3 address) wird jetzt im URL-Pfad übergeben. Komponentenfilter (v3 components) werden jetzt als address.*-Abfrageparameter übergeben.
bounds	locationBias.rectangle	Umbenannt; Struktur in Objekt geändert.
language	languageCode	Umbenannt.
region	regionCode	Umbenannt.
extra_computations	Entfernt

Änderungen an Antwortfeldern

v3-Feld	v4-Feld	Hinweise
status, error_message	Entfernt	In Version 4 werden HTTP-Statuscodes und Fehlertexte verwendet.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Umbenannt.
results.geometry.location_type	results.granularity	Umbenannt.
results.geometry.location	results.location	Feldnamen: lat/lng –> latitude/longitude.
results.geometry.viewport	results.viewport	Feldnamen: northeast/southwest –> high/low.
results.postcode_localities	results.postalCodeLocalities	Umbenannt. Wird jetzt für einen oder mehrere Orte zurückgegeben (v3 erforderlich > 1).
results.partial_match	Entfernt
Neu	results.addressComponents.languageCode	Sprache der jeweiligen Adresskomponente.
Neu	results.bounds	Explizite Grenzen mit high/low.
Neu	results.place	Ressourcenname für den Ort.
Neu	results.postalAddress	Strukturiertes PostalAddress-Objekt.

Von v3 der umgekehrten Geocodierung migrieren

Wenn Sie Reverse Geocoding verwenden, um Koordinaten in Adressen umzuwandeln, sollten Sie zum v4-Endpunkt Reverse geocode a location (Umgekehrte Geocodierung eines Standorts) migrieren, der eine GET-Anfrage akzeptiert.

In der Version 4 der API wurden Namen, Struktur und Unterstützung für mehrere Parameter geändert. Wir empfehlen dringend, eine Feldmaske zu verwenden, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen.

Warnung :In allen v4-Endpunkten werden Feldnamen im Lower Camel Case formatiert (z. B. „addressComponents“). In v3-Endpunkten wurde dagegen die Snake-Case-Schreibweise verwendet (z. B. „address_components“). In Version 4 wird für RPC-Antworten weiterhin Snake Case verwendet, wie in Version 3.

Änderungen an Anfrageparametern

v3-Parameter	v4-Parameter	Hinweise
language	languageCode	Umbenannt.
region	regionCode	Umbenannt.
result_type	types	Umbenannt; verwendet wiederholte Abfrageparameter.
location_type	granularity	Umbenannt; verwendet wiederholte Abfrageparameter.
extra_computations	Entfernt

Änderungen an Antwortfeldern

v3-Feld	v4-Feld	Hinweise
status, error_message	Entfernt	In Version 4 werden HTTP-Statuscodes und Fehlertexte verwendet.
results.address_components.long_name/results.address_components.short_name	results.addressComponents.longText/results.addressComponents.shortText	Umbenannt.
results.geometry.location_type	results.granularity	Umbenannt.
results.geometry.location	results.location	Feldnamen: lat/lng –> latitude/longitude.
results.geometry.viewport	results.viewport	Feldnamen: northeast/southwest –> high/low.
Neu	results.addressComponents.languageCode	Sprache der jeweiligen Adresskomponente.
Neu	results.bounds	Explizite Grenzen mit high/low.
Neu	results.place	Ressourcenname für den Ort.
Neu	results.postalAddress	Strukturiertes PostalAddress-Objekt.

Von v3 Place Geocoding migrieren

Wenn Sie place_id verwenden, um die Adresse für eine bestimmte Orts-ID mit Geocoding v3 abzurufen, müssen Sie zum Endpunkt Place Geocoding in Version 4 migrieren, der eine GET-Anfrage akzeptiert.

In der Version 4 der API wurden Namen, Struktur und Unterstützung für mehrere Parameter geändert. Wir empfehlen dringend, eine Feldmaske zu verwenden, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen.

Warnung :In allen v4-Endpunkten werden Feldnamen im Lower Camel Case formatiert (z. B. „addressComponents“). In v3-Endpunkten wurde dagegen die Snake-Case-Schreibweise verwendet (z. B. „address_components“). In Version 4 wird für RPC-Antworten weiterhin Snake Case verwendet, wie in Version 3.

Änderungen an Anfrageparametern

v3-Parameter	v4-Parameter	Hinweise
place_id	Feld place im Anfrage-Proto	Die Orts-ID wird jetzt als Pfadparameter places/{place} angegeben, z. B. https://geocode.googleapis.com/v4beta/geocode/places/ChIJj61dQgK6j4AR4GeTYWZsKWw. Dies entspricht dem Feld „place“ in der zugrunde liegenden Anfrage.
language	languageCode	Umbenannt.
region	regionCode	Umbenannt.

Änderungen an Antwortfeldern

v3-Feld	v4-Feld	Hinweise
status, error_message	Entfernt	In Version 4 werden HTTP-Statuscodes und Fehlertexte verwendet.
results	(root)	Version 4 gibt ein einzelnes Ergebnisobjekt zurück, kein results-Array.
results.address_components.long_name/results.address_components.short_name	addressComponents.longText/addressComponents.shortText	Umbenannt.
results.geometry.location_type	granularity	Umbenannt.
results.geometry.location	location	Feldnamen: lat/lng –> latitude/longitude.
results.geometry.viewport	viewport	Feldnamen: northeast/southwest –> high/low.
results.postcode_localities	postalCodeLocalities	Umbenannt. Wird jetzt für einen oder mehrere Orte zurückgegeben (v3 erforderlich > 1).
Neu	addressComponents.languageCode	Sprache der jeweiligen Adresskomponente.
Neu	bounds	Explizite Grenzen mit high/low.
Neu	place	Ressourcenname für den Ort.
Neu	postalAddress	Strukturiertes PostalAddress-Objekt.

Von der Geocoding Hyperlocal Data API zur Destinations API migrieren

Die folgenden Funktionen in der Geocoding API v3 werden durch den SearchDestinations-Endpunkt der Geocoding API v4 ersetzt:

• Einstiege
• Navigationspunkte
• Gebäudeumrisse
• Außengelände

Wenn Sie die Geocoding API v3 für die oben genannten Funktionen verwendet haben, können Sie in diesem Dokument nachlesen, wie Sie stattdessen den SearchDestinations-Endpunkt verwenden. In diesem Dokument wird erläutert, wo in der SearchDestinations API-Antwort diese Funktionen zu finden sind, und es werden Unterschiede in der Darstellung dieser Funktionen in den API-Antworten zwischen der Geocoding API v3 und dem SearchDestinations-Endpunkt der Geocoding API v4 beschrieben.

Einstiege

Verwenden Sie das Feld destination.entrances, um die Eingänge abzurufen, die mit einem destination verknüpft sind.

Das Format eines entrance unterscheidet sich geringfügig vom Eingangsformat in der Geocoding API v3. Jeder Eintrag in destination.entrances hat die folgenden Felder:

• displayName: Dies ist ein neues optionales Feld mit einem für Menschen lesbaren Namen für den Eingang, z. B. „Tor B“.
• location – Dies ist ein Ort vom Typ LatLng, der sich vom Format der Geocoding API v3 unterscheidet.
• tags: Dies entspricht dem Feld tags der Eingänge aus der Geocoding API v3.
• place: Analog zum Feld buildingPlaceId der Eingänge aus der Geocoding API v3. Die Orts-ID in diesem Feld kann jedoch für einen Ort beliebigen Typs sein, nicht nur für ein Gebäude.

Navigationspunkte

Verwenden Sie das Feld destination.navigationPoints, um die Navigationspunkte abzurufen, die mit einem destination verknüpft sind.

Das Format von navigationPoint unterscheidet sich leicht vom Format für Navigationspunkte in der Geocoding API v3. Jeder Navigationspunkt in destination.navigationPoints hat die folgenden Felder:

• displayName: Dies ist ein neues optionales Feld mit einem für Menschen lesbaren Namen für den Navigationspunkt, z. B. „5th Ave“.
• location – Dies ist ein Ort vom Typ LatLng, der sich vom Format der Geocoding API v3 unterscheidet.
• travelModes: Dies entspricht dem Feld restrictedTravelModes der Navigationspunkte aus der Geocoding API v3. Die möglichen Enum-Werte sind dieselben. Der einzige Unterschied besteht darin, dass dieses Feld jetzt die zulässigen Fortbewegungsmittel für den Navigationspunkt und nicht die eingeschränkten Fortbewegungsmittel darstellt.
• usage: Dies ist ein neues Feld, das die vom Navigationspunkt unterstützten Anwendungsfälle enthält. Die meisten Navigationspunkte haben eine UNKNOWN-Nutzung. Das bedeutet aber nicht unbedingt, dass die Nutzung des Navigationspunkts in irgendeiner Weise eingeschränkt ist.

Gebäudeumrisse

Wenn Sie die mit einem destination verknüpften Gebäudeumrisse abrufen möchten, sollten Sie das Feld displayPolygon der placeView-Objekte im destination verwenden, die Gebäude darstellen. Für jedes placeView können Sie mit dem Feld placeView.structureType prüfen, ob es sich um ein Gebäude handelt. Wenn der Strukturtyp BUILDING ist, können Sie den Umriss aus dem Feld placeView.displayPolygon abrufen. Das placeView enthält auch zusätzliche Felder für das Gebäude, die in der Geocoding API v3 nicht vorhanden waren.

Hinweis :Sie suchen nur nach dem Gebäude-Polygon an einem bestimmten Ort? Mit dem Parameter placeFilter in Ihrer Anfrage können Sie die Ergebnisse eingrenzen. Wenn Sie nur Gebäudeergebnisse zurückgeben möchten, legen Sie structureType in placeFilter auf "BUILDING" fest. Wenn Sie vor allem ein Polygon erhalten möchten (auch für Orte ohne genaue Adressen), setzen Sie addressability in placeFilter auf "ANY", um das genaueste verfügbare Polygon zurückzugeben.

Beispiel

{
  "locationQuery": {
    "location": {
      "latitude": 37.4224,
      "longitude": -122.0841
    },
    "placeFilter": {
      "structureType": "BUILDING",
      "addressability": "ANY"
    }
  }
}
  

Ein destination kann ein placeView-Objekt enthalten, das ein Gebäude in den folgenden Feldern darstellt:

• destination.primary: Dies ist der primäre Ort für das Ziel.
• destination.containingPlaces: Dies ist ein wiederkehrendes Feld, das größere Orte enthalten kann, die den primären Ort „enthalten“. Wenn der primäre Ort beispielsweise ein subpremise ist, enthält containingPlaces in der Regel die placeView, die das Gebäude darstellt.
• destination.subDestinations: Dies ist ein wiederkehrendes Feld, das untergeordnete Ziele des primären Orts enthalten kann. Beispielsweise einzelne Wohneinheiten eines Gebäudes. Dieses Feld enthält in der Regel kein placeView für ein Gebäude.

Das Format von placeView.displayPolygon entspricht dem Format für Gebäudeumrisse in der Geocoding API v3, also dem GeoJSON-Format, das dem RFC 7946-Format entspricht.

Außengelände

Ähnlich wie beim Erstellen von Umrisslinien sollten Sie zum Abrufen der mit einem destination verknüpften Grundstücke das Feld displayPolygon der placeView-Objekte im destination verwenden, die Grundstücke darstellen. Für jede placeView können Sie mit dem Feld placeView.structureType prüfen, ob es sich um einen Grund handelt. Wenn der Strukturtyp GROUNDS ist, können Sie die Gliederung aus dem Feld placeView.displayPolygon abrufen. Die placeView enthält auch zusätzliche Felder für die Gründe, die in der Geocoding API v3 nicht vorhanden waren.

Ein destination kann ein placeView-Objekt enthalten, das einen Grund in den folgenden Feldern darstellt:

• destination.primary
• destination.containingPlaces
• destination.subDestinations

Das Format von placeView.displayPolygon entspricht dem Format für die Umrisslinie von Grundstücken in der Geocoding API v3, also dem GeoJSON-Format gemäß RFC 7946.

Feldmaske verwenden, um diese Funktionen anzufordern

Für den Endpunkt SearchDestinations ist eine Feldmaske erforderlich, wie unter Zurückzugebende Felder auswählen beschrieben. Die Feldmaske kann auf * gesetzt werden, um alle Felder zurückzugeben. Sie können sie aber auch auf die gewünschten Felder festlegen. Mit der folgenden API-Anfrage wird beispielsweise die Feldmaske so festgelegt, dass alle Felder abgerufen werden, die zum Abrufen der Eingänge, Navigationspunkte, Gebäudeumrisse und Grundstücke eines Ziels erforderlich sind:

curl -X POST -d '{"place": "places/ChIJG3kh4hq6j4AR_XuFQnV0_t8"}' \
  -H "X-Goog-Api-Key: API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Goog-FieldMask: destinations.entrances,destinations.navigationPoints,destinations.primary,destinations.containingPlaces,destinations.subDestinations" \
  https://geocode.googleapis.com/v4alpha/geocode/destinations