Anfragen
Eine Geocoding API-Anfrage weist folgendes Format auf:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
Dabei kann outputFormat
einen der folgenden Werte haben:
json
(empfohlen) verweist auf eine Ausgabe in JSON (JavaScript Object Notation).xml
gibt die Ausgabe in XML an.
Bei Anfragen mit API-Schlüssel ist HTTPS erforderlich.
Einige Parameter sind erforderlich, während andere optional verwendet werden können. Wie bei URLs üblich, werden Parameter durch das kaufmännische Und-Zeichen (&
) getrennt.
Im Folgenden wird die Geocodierung und die umgekehrte Geocodierung separat beschrieben, da für jede Art von Anfrage unterschiedliche Parameter verfügbar sind.
Geocodierungsparameter (Breiten-/Längengrad-Suche)
Erforderliche Parameter in Geocoding-Anfragen:
address
: Die Adresse oder der Plus Code, den Sie geocodieren möchten. Geben Sie Adressen in dem Format an, das vom Postdienst des betreffenden Landes verwendet wird. Zusätzliche Adresselemente wie Unternehmensnamen und -einheiten, Suite- oder Stockwerknummern sollten vermieden werden. Adresselemente sollten durch Leerzeichen begrenzt werden (hier als URL-Escaping als%20
angezeigt):address=24%20Sussex%20Drive%20Ottawa%20ON
Formatieren Sie Plus Codes wie hier dargestellt (Pluszeichen werden mit der URL (%2B
) maskiert, Leerzeichen als%20
):- Global Code besteht aus einem vierstelligen Ortscode und einem lokalen Code mit mindestens 6 Zeichen (849VCWC8+R9 ist
849VCWC8%2BR9
). - Compound Code ist ein mindestens 6-stelliger lokaler Code mit einem expliziten Ort (CWC8+R9 Mountain View, CA, USA ist
CWC8%2BR9%20Mountain%20View%20CA%20USA
).
--OR--
components
: Ein Komponentenfilter, bei dem Elemente durch einen senkrechten Strich (|
) getrennt sind. Der Komponentenfilter wird auch als optionaler Parameter akzeptiert, wennaddress
angegeben ist. Jedes Element im Komponentenfilter besteht aus einemcomponent:value
-Paar und schränkt die Ergebnisse des Geocoders vollständig ein. Weitere Informationen zum Filtern von Komponenten finden Sie unten.- Global Code besteht aus einem vierstelligen Ortscode und einem lokalen Code mit mindestens 6 Zeichen (849VCWC8+R9 ist
key
: Der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung zum Zweck der Kontingentverwaltung. Hier erfahren Sie, wie Sie einen Schlüssel abrufen.
Weitere Informationen finden Sie in den FAQs.
Optionale Parameter in einer Geocoding-Anfrage:
bounds
: Der Begrenzungsrahmen des Darstellungsbereichs, innerhalb dessen die Geocodierungsergebnisse stärker gewichtet werden sollen. Durch diesen Parameter werden die Ergebnisse des Geocoders zwar beeinflusst, aber nicht vollständig eingeschränkt. Weitere Informationen finden Sie unter Gewichtung des Darstellungsbereichs unten.language
: Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.- Hier finden Sie eine Liste der unterstützten Sprachen. Die unterstützten Sprachen werden von Google häufig aktualisiert. Die Liste ist daher unter Umständen nicht vollständig.
- Wird
language
nicht angegeben, versucht der Geocoder, die imAccept-Language
-Header angegebene bevorzugte Sprache oder die Muttersprache der Domain zu verwenden, von der die Anfrage gesendet wird. - Der Geocoder versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Zu diesem Zweck werden Adressen in der lokalen Sprache zurückgegeben und bei Bedarf in eine für den Nutzer lesbare Schrift transkribiert. 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 aus der ersten Komponente ausgewählt wird.
- Wenn der Name nicht in der bevorzugten Sprache verfügbar ist, verwendet der Geocoder die höchste Übereinstimmung.
- Die bevorzugte Sprache hat einen geringen Einfluss auf die Menge der Ergebnisse, die die API zurückgibt, und auf die Reihenfolge, in der sie zurückgegeben werden. Abkürzungen werden vom Geocoder je nach Sprache unterschiedlich interpretiert. Das können z. B. Abkürzungen für Straßentypen oder Synonyme sein, die in einer Sprache gültig sein, in einer anderen aber nicht. Zum Beispiel sind utca und tér Synonyme für Straße und Platz auf Ungarisch.
region
: Der Regionscode, angegeben als zweistelliger ccTLD-Wert („Top-Level-Domain“). Durch diesen Parameter werden die Ergebnisse des Geocoders zwar beeinflusst, aber nicht vollständig eingeschränkt. Weitere Informationen finden Sie unten unter Gewichtung nach Region. Der Parameter kann sich auch nach anwendbarem Recht auf die Ergebnisse auswirken.components
: Ein Komponentenfilter, bei dem Elemente durch einen senkrechten Strich (|
) getrennt sind. Der Komponentenfilter ist erforderlich, wenn die Anfrage keinaddress
enthält. Jedes Element im Komponentenfilter besteht aus einemcomponent:value
-Paar und schränkt die Ergebnisse des Geocoders vollständig ein. Weitere Informationen zum Filtern von Komponenten finden Sie unten.
Antworten
Geocoding-Antworten werden in dem Format zurückgegeben, das in der URL-Anfrage mit dem Flag output
angegeben wird, oder standardmäßig im JSON-Format.
In diesem Beispiel fordert die Geocoding API eine json
-Antwort für eine Suchanfrage nach der Orts-ID „ChIJeRpOeF67j4AR9ydy_PIzPuM“ an. Diese Orts-ID gilt für das Gebäude in 1600 Amphitheatre Parkway, Mountain View, CA.
Diese Anfrage veranschaulicht die Verwendung des JSON-Flags output
:
https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Diese Anfrage veranschaulicht die Verwendung des XML-Flags output
:
https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY
Über die Tabs unten kannst du dir die JSON- und XML-Beispielantworten ansehen.
JSON
{ "results": [ { "address_components": [ { "long_name": "1600", "short_name": "1600", "types": [ "street_number" ] }, { "long_name": "Amphitheatre Parkway", "short_name": "Amphitheatre Pkwy", "types": [ "route" ] }, { "long_name": "Mountain View", "short_name": "Mountain View", "types": [ "locality", "political" ] }, { "long_name": "Santa Clara County", "short_name": "Santa Clara County", "types": [ "administrative_area_level_2", "political" ] }, { "long_name": "California", "short_name": "CA", "types": [ "administrative_area_level_1", "political" ] }, { "long_name": "United States", "short_name": "US", "types": [ "country", "political" ] }, { "long_name": "94043", "short_name": "94043", "types": [ "postal_code" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4224428, "lng": -122.0842467 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4239627802915, "lng": -122.0829089197085 }, "southwest": { "lat": 37.4212648197085, "lng": -122.0856068802915 } } }, "place_id": "ChIJeRpOeF67j4AR9ydy_PIzPuM", "plus_code": { "compound_code": "CWC8+X8 Mountain View, CA", "global_code": "849VCWC8+X8" }, "types": [ "street_address" ] } ], "status": "OK" }
Beachten Sie, dass die JSON-Antwort zwei Stammelemente enthält:
"status"
enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unter Statuscodes unten."results"
enthält ein Array geocodierter Adress- und Geometriedaten.
Im Allgemeinen wird für die Adresssuche nur ein Eintrag im "results"
-Array zurückgegeben. Der Geocoder kann jedoch mehrere Ergebnisse zurückgeben, wenn die Adressabfragen nicht eindeutig sind.
XML
<GeocodeResponse> <status>OK</status> <result> <type>street_address</type> <formatted_address>1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA</formatted_address> <address_component> <long_name>1600</long_name> <short_name>1600</short_name> <type>street_number</type> </address_component> <address_component> <long_name>Amphitheatre Parkway</long_name> <short_name>Amphitheatre Pkwy</short_name> <type>route</type> </address_component> <address_component> <long_name>Mountain View</long_name> <short_name>Mountain View</short_name> <type>locality</type> <type>political</type> </address_component> <address_component> <long_name>Santa Clara County</long_name> <short_name>Santa Clara County</short_name> <type>administrative_area_level_2</type> <type>political</type> </address_component> <address_component> <long_name>California</long_name> <short_name>CA</short_name> <type>administrative_area_level_1</type> <type>political</type> </address_component> <address_component> <long_name>United States</long_name> <short_name>US</short_name> <type>country</type> <type>political</type> </address_component> <address_component> <long_name>94043</long_name> <short_name>94043</short_name> <type>postal_code</type> </address_component> <geometry> <location> <lat>37.4224428</lat> <lng>-122.0842467</lng> </location> <location_type>ROOFTOP</location_type> <viewport> <southwest> <lat>37.4212648</lat> <lng>-122.0856069</lng> </southwest> <northeast> <lat>37.4239628</lat> <lng>-122.0829089</lng> </northeast> </viewport> </geometry> <place_id>ChIJeRpOeF67j4AR9ydy_PIzPuM</place_id> <plus_code> <global_code>849VCWC8+X8</global_code> <compound_code>CWC8+X8 Mountain View, CA</compound_code> </plus_code> </result> </GeocodeResponse>
Die XML-Antwort besteht aus einer einzigen <GeocodeResponse>
und zwei Elementen auf oberster Ebene:
<status>
enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unter Statuscodes weiter unten.- Null oder mehr
<result>
-Elemente, von denen jedes einen einzelnen Satz geocodierter Adress- und Geometriedaten enthält.
Die XML-Antwort ist erheblich länger als die JSON-Antwort. Aus diesem Grund empfehlen wir, json
als bevorzugtes Ausgabe-Flag zu verwenden, es sei denn, Ihr Dienst erfordert aus irgendeinem Grund xml
.
Außerdem erfordert die Verarbeitung von XML-Strukturen einige Sorgfalt, damit auf die richtigen Knoten und Elemente verwiesen wird. Unter
Parsing von XML mit XPath finden Sie einige empfohlene Designmuster für die Ausgabeverarbeitung.
- XML-Ergebnisse sind von einem
<GeocodeResponse>
-Stammelement umschlossen. - JSON gibt Einträge mit mehreren Elementen durch Pluralarrays (
types
) an, während XML diese Einträge mit mehreren einzelnen Elementen (<type>
) angibt. - Leere Elemente werden in JSON durch leere Arrays angegeben, in XML dagegen durch das Fehlen eines solchen Elements. Eine Antwort, durch die keine Ergebnisse generiert werden, gibt beispielsweise ein leeres
results
-Array in JSON, aber keine<result>
-Elemente in XML zurück.
Statuscodes
Das Feld "status"
innerhalb des Geocoding-Antwortobjekts enthält den Status der Anfrage sowie möglicherweise Informationen zur Fehlerbehebung, anhand derer Sie herausfinden können, warum die Geocodierung nicht funktioniert. Das Feld "status"
kann die folgenden Werte enthalten:
"OK"
gibt an, dass die Adresse ohne Fehler geparst und mindestens ein Geocode zurückgegeben wurde."ZERO_RESULTS"
gibt an, dass die Geocodierung erfolgreich war, aber keine Ergebnisse zurückgegeben wurden. Dieser Status kann ausgegeben werden, wenn dem Geocoder ein nicht vorhandenesaddress
-Element übergeben wurde.OVER_DAILY_LIMIT
gibt einen der folgenden Werte an:- Der API-Schlüssel fehlt oder ist ungültig.
- Die Abrechnung wurde für Ihr Konto nicht aktiviert.
- Eine selbst festgelegte Nutzungsbeschränkung wurde überschritten.
- Die angegebene Zahlungsmethode ist nicht mehr gültig (z. B. weil eine Kreditkarte abgelaufen ist).
Informationen zur Behebung dieses Problems finden Sie in den FAQs zu Google Maps.
"OVER_QUERY_LIMIT"
gibt an, dass Sie Ihr Kontingent überschritten haben."REQUEST_DENIED"
gibt an, dass Ihre Anfrage abgelehnt wurde."INVALID_REQUEST"
gibt im Allgemeinen an, dass die Anfrage (address
,components
oderlatlng
) fehlt."UNKNOWN_ERROR"
gibt an, dass die Anfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Möglicherweise ist die Anfrage erfolgreich, wenn Sie es noch einmal versuchen.
Fehlermeldungen
Wenn der Geocoder einen anderen Statuscode als OK
zurückgibt, enthält das Geocoding-Antwortobjekt möglicherweise ein zusätzliches error_message
-Feld. Dieses Feld enthält ausführlichere Informationen zu den Gründen für den jeweiligen Statuscode.
Ergebnisse
Vom Geocoder zurückgegebene Ergebnisse werden in ein JSON-Array results
eingefügt. Auch wenn der Geocoder keine Ergebnisse zurückgibt (z. B. weil die Adresse nicht existiert), wird ein leeres results
-Array zurückgegeben. XML-Antworten bestehen aus null oder mehr <result>
-Elementen.
Ein typisches Ergebnis enthält die folgenden Felder:
- Das Array
types[]
gibt den Typ des zurückgegebenen Ergebnisses an. Dieses Array enthält eine Reihe von null oder mehr Tags, mit denen der Typ des im Ergebnis zurückgegebenen Elements bestimmt wird. Ein Geocode für „Chicago“ gibt beispielsweise „locality“ zurück, was bedeutet, dass Chicago eine Stadt ist, sowie „political“, was bedeutet, dass Chicago eine politische Einheit ist. Bei Komponenten kann ein leeres Typenarray vorhanden sein, wenn für diese Adresskomponente keine Typen bekannt sind. Die API kann bei Bedarf neue Typwerte hinzufügen. Weitere Informationen finden Sie unter Adresstypen und Adresskomponenten. formatted_address
ist ein String, der die Adresse dieses Ortes in lesbarer Form enthält.Diese Adresse stimmt häufig mit der Postanschrift überein. In einigen Ländern, z. B. dem Vereinigten Königreich, ist die Weitergabe echter Postanschriften aufgrund von Lizenzeinschränkungen nicht zulässig.
Die formatierte Adresse besteht aus einer oder mehreren Adresskomponenten. Die Adresse „111 8th Avenue, New York, NY“ besteht z. B. aus den folgenden Komponenten: „111“ (Hausnummer), „8th Avenue“ (Straße), „New York“ (Stadt) und „NY“ (US-Bundesstaat).
Wir raten davon ab, die formatierte Adresse programmatisch zu parsen. Verwenden Sie stattdessen die einzelnen Adresskomponenten, die zusätzlich zur formatierten Adresse in der API-Antwort enthalten sind.
address_components[]
ist ein Array, das die einzelnen Komponenten für diese Adresse enthält.Jede Adresskomponente enthält normalerweise die folgenden Felder:
types[]
ist ein Array, das den Typ der Adresskomponente angibt. Sehen Sie sich die Liste der unterstützten Typen an.long_name
ist die Volltextbeschreibung oder der Name der Adresskomponente, wie vom Geocoder zurückgegeben.short_name
ist ein abgekürzter Textname für die Adresskomponente, falls vorhanden. Beispielsweise könnte eine Adresskomponente für den US-Bundesstaat Alaska denlong_name
„Alaska“ und denshort_name
„AK“ haben, entsprechend der postalischen Abkürzung.
Hinweise zum
address_components[]
-Array:- Das Array der Adresskomponenten kann mehr Komponenten als nur
formatted_address
enthalten. - Das Array enthält nicht unbedingt alle politischen Einheiten einer Adresse. Ausgenommen hiervon sind die im
formatted_address
enthaltenen. Wenn Sie alle politischen Einheiten abrufen möchten, die zu einer bestimmten Adresse gehören, müssen Sie die umgekehrte Geocodierung verwenden. Dabei wird der Breiten-/Längengrad der Adresse als Parameter an die Anfrage übergeben. - Es kann nicht garantiert werden, dass das Antwortformat zwischen mehreren Anfragen gleich bleibt. Insbesondere die Anzahl der
address_components
variiert je nach angeforderter Adresse und kann sich im Laufe der Zeit für dieselbe Adresse ändern. Die Position einer Komponente im Array ändert sich unter Umständen. Auch der Typ der Komponente kann sich ändern. In einer späteren Anfrage fehlt evtl. auch eine bestimmte Komponente.
Zur Verarbeitung des Komponentenarrays sollten Sie die Antwort parsen und geeignete Werte mithilfe von Ausdrücken auswählen. Weitere Informationen findest du in der Anleitung zum Parsing einer Antwort.
postcode_localities[]
ist ein Array mit bis zu 100 Orten in einer Postleitzahl. Dieses Element ist nur vorhanden, wenn das Ergebnis eine Postleitzahl ist, die mehrere Orte enthält.geometry
enthält die folgenden Informationen:location
enthält den geocodierten Breiten- und Längengradwert. Bei normalen Adresssuchen ist dieses Feld in der Regel am wichtigsten.location_type
enthält zusätzliche Daten zum angegebenen Ort. Folgende Werte werden derzeit unterstützt:"ROOFTOP"
gibt an, dass das zurückgegebene Ergebnis ein präziser Geocode ist, für den Standortinformationen bis zur Straßenebene vorliegen."RANGE_INTERPOLATED"
gibt an, dass das zurückgegebene Ergebnis eine Näherung darstellt (normalerweise auf einer Straße), die zwischen zwei präzisen Punkten (z. B. Kreuzungen) interpoliert wurde. Interpolierte Ergebnisse werden in der Regel zurückgegeben, wenn hausnummerngenaue Geocodierungen für eine Adresse nicht verfügbar sind."GEOMETRIC_CENTER"
gibt an, dass das zurückgegebene Ergebnis der geometrische Mittelpunkt eines Ergebnisses wie z. B. einer Polylinie (z. B. einer Straße) oder eines Polygons (eine Region) ist."APPROXIMATE"
gibt an, dass das zurückgegebene Ergebnis eine Näherung ist.
viewport
enthält den empfohlenen Darstellungsbereich zum Anzeigen des zurückgegebenen Ergebnisses. Dieser wird in Form von zwei Breiten- und Längengradwerten angegeben, die diesouthwest
- undnortheast
-Ecke des Begrenzungsrahmens des Darstellungsbereichs definieren. Im Allgemeinen wird der Darstellungsbereich dazu verwendet, ein Ergebnis in den Rahmen zu setzen, wenn es einem Nutzer angezeigt wird.bounds
(optional zurückgegeben) speichert den Begrenzungsrahmen, der das zurückgegebene Ergebnis vollständig enthalten kann. Diese Begrenzungen stimmen möglicherweise nicht mit dem empfohlenen Darstellungsbereich überein. San Francisco umfasst beispielsweise die Farallon-Inseln, die zwar technisch Teil der Stadt sind, aber wahrscheinlich nicht im Darstellungsbereich zurückgegeben werden sollten.
-
plus_code
(siehe Offener Standortcode und Plus Codes) ist ein codierter Standortverweis, der aus Breiten- und Längengraden abgeleitet wird und ein Gebiet darstellt, das 1/8.000. Grad eines Grades mal 1/8.000 Grad (etwa 14 m x 14 m am Äquator) oder kleiner darstellt. Plus Codes können als Ersatz für Adressen an Orten verwendet werden, an denen keine Adressen vorhanden sind, z. B. wenn Gebäude nicht nummeriert oder Straßen nicht benannt sind. Die API gibt nicht immer Plus Codes zurück.Wenn der Dienst einen Plus Code zurückgibt, wird er als globaler Code und als zusammengesetzter Code formatiert:
global_code
besteht aus einem vierstelligen Gebietscode und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9).compound_code
ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort (CWC8+R9, Mountain View, CA, USA). Wir raten davon ab, diesen Code programmatisch zu parsen.
-
partial_match
gibt an, dass der Geocoder keine genaue Übereinstimmung für die ursprüngliche Anfrage zurückgegeben hat, obwohl ein Teil der angeforderten Adresse zugeordnet werden konnte. Wir empfehlen, die ursprüngliche Anfrage auf Tippfehler und/oder Vollständigkeit zu prüfen.Teilweise Übereinstimmungen treten am häufigsten bei Adressen auf, die nicht in dem Ort vorhanden sind, der in der Anfrage übergeben wird. Sie werden unter Umständen auch zurückgegeben, wenn eine Anfrage mit mehreren Adressen in einem Ort übereinstimmt. Wird „Henr St, Bristol, UK“ angefragt, wird z. B. eine teilweise Übereinstimmung für die Henry Street und die Henrietta Street zurückgegeben. Enthält eine Anfrage eine Adresskomponente mit Tippfehler, wird vom Geocoding-Dienst möglicherweise eine andere Adresse vorgeschlagen. Solche Vorschläge werden auch als teilweise Übereinstimmung gekennzeichnet.
place_id
ist eine eindeutige Kennung, die mit anderen Google APIs verwendet werden kann. Sie können dasplace_id
beispielsweise in einer Places API-Anfrage verwenden, um Details zu einem lokalen Unternehmen wie Telefonnummer, Öffnungszeiten oder Nutzerrezensionen abzurufen. Weitere Informationen finden Sie in der Übersicht zur Orts-ID.
Adresstypen und Adresskomponententypen
Das Array types[]
im Ergebnis gibt den Adresstyp an. Beispiele für Adresstypen sind Adresse, Land oder Verwaltungseinheit. Es gibt auch ein types[]
-Array in address_components[]
, das den Typ jedes Teils der Adresse angibt. Dazu gehören bspw. Hausnummer oder Land. (Nachfolgend finden Sie eine vollständige Liste der Typen.) Adressen können mehrere Typen aufweisen. Die Typen können als „Tags“ betrachtet werden.
Viele Städte haben z. B. Tags vom Typ political
und locality
.
Die folgenden Typen werden vom Geocoder sowohl im Array „address type“ als auch im Array „address component“ unterstützt und zurückgegeben:
street_address
gibt eine genaue Adresse an.route
gibt eine Straße mit einer Bezeichnung an, z. B. „B1“.intersection
gibt eine größere Kreuzung, üblicherweise von 2 Hauptstraßen an.political
gibt eine politische Einheit an. Dieser Typ stellt meistens ein Polygon einer öffentlichen Einrichtung dar.country
gibt eine staatliche politische Einheit (Land) an und ist normalerweise der Typ mit dem höchsten Rang, der vom Geocoder zurückgegeben wird.administrative_area_level_1
gibt eine öffentliche Verwaltungseinheit 1 Stufe unterhalb der Landesebene an. In den USA sind diese Verwaltungsebenen z. B. die Bundesstaaten. Diese Verwaltungsebenen gibt es nicht in allen Ländern. In den meisten Fällen sind Kurzbezeichnungen dieses Typs eng an die Untereinheiten des Standards ISO 3166-2 und andere gängige Definitionen angelehnt. Eine Garantie hierfür können wir jedoch nicht geben, da unsere Geocoding-Ergebnisse auf verschiedenen Signalen und Standortdaten basieren.administrative_area_level_2
gibt eine öffentliche Verwaltungseinheit 2 Stufen unterhalb der Landesebene an. In den USA sind diese Verwaltungsebenen z. B. die Countys. Diese Verwaltungsebenen gibt es nicht in allen Ländern.administrative_area_level_3
gibt eine öffentliche Verwaltungseinheit 3 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.administrative_area_level_4
gibt eine öffentliche Verwaltungseinheit 4 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.administrative_area_level_5
gibt eine öffentliche Verwaltungseinheit 5 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.administrative_area_level_6
gibt eine öffentliche Verwaltungseinheit 6 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.administrative_area_level_7
gibt eine öffentliche Verwaltungseinheit 7 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.colloquial_area
gibt eine gängige alternative Bezeichnung für die Einheit an.locality
gibt die politische Einheit einer Stadt oder Gemeinde an.sublocality
gibt eine öffentliche Verwaltungseinheit eine Stufe unterhalb des Ortes an. Für einige Standorte wird möglicherweise einer der folgenden zusätzlichen Typen ausgegeben:sublocality_level_1
bissublocality_level_5
. Jede dieser Ebenen entspricht einer Verwaltungseinheit. Je höher die Zahl, desto kleiner das geografische Gebiet.neighborhood
gibt ein benanntes Stadtviertel an.premise
gibt einen benannten Ort an, normalerweise ein Gebäude oder einen Komplex von Gebäuden mit einem gemeinsamen Namen.subpremise
gibt eine erstrangige Einheit unterhalb der Ebene eines benannten Ortes an, normalerweise ein einzelnes Gebäude innerhalb eines Gebäudekomplexes mit einem gemeinsamen Namen.plus_code
gibt einen codierten Verweis auf den Standort an, der sich aus Breiten- und Längengrad ableiten lässt. Plus Codes können als Ersatz für Adressen verwendet werden, wenn keine Adressen vorhanden sind, z. B. wenn Gebäude keine Hausnummern oder Straßen keine Namen haben. Weitere Informationen finden Sie unter https://plus.codes.postal_code
gibt eine Postleitzahl an, wie sie zum Adressieren von Postsendungen innerhalb des Landes verwendet wird.natural_feature
gibt ein auffallendes Landschaftsmerkmal an.airport
gibt einen Flughafen an.park
gibt einen benannten Park an.point_of_interest
gibt einen benannten POI an. In der Regel sind diese POIs bekannte lokale Objekte, die sich keiner anderen Kategorie zuordnen lassen, z. B. das Brandenburger Tor oder der Eiffelturm.
Eine leere Typenliste bedeutet, dass für eine bestimmte Adresskomponente keine Typen vorhanden sind, wie z. B. ein Lieu-dit in Frankreich.
Zusätzlich zu den oben genannten können Adresskomponenten auch die hier aufgeführten Typen enthalten. Diese Liste ist nicht vollständig und kann sich ändern.
floor
gibt das Stockwerk innerhalb einer Gebäudeadresse an.establishment
gibt normalerweise einen Ort an, der noch nicht kategorisiert wurde.landmark
gibt einen Ort in der Nähe an, der als Referenz zur Orientierung dient.point_of_interest
gibt einen benannten POI an.parking
gibt einen Parkplatz oder ein Parkhaus an.post_box
gibt einen bestimmten Briefkasten an.postal_town
gibt eine Gruppe geografischer Gebiete wielocality
undsublocality
an, die in einigen Ländern als Postanschriften verwendet werden.room
gibt den Raum innerhalb einer Gebäudeadresse an.street_number
gibt die genaue Hausnummer an.bus_station
,train_station
undtransit_station
geben den Standort einer Haltestelle für Bus, Bahn oder ein anderes öffentliches Verkehrsmittel an.
Gewichtung nach Darstellungsbereich
In einer Geocoding-Anfrage können Sie den Geocoding-Dienst so einrichten, dass Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) bevorzugt werden. Dazu legen Sie in der Anfrage-URL den Parameter bounds
fest.
Der Parameter bounds
definiert die Breiten-/Längengradkoordinaten der südwestlichen und nordöstlichen Ecke dieses Begrenzungsrahmens, wobei zum Trennen der Koordinaten ein Pipe-Zeichen (|
) verwendet wird.
Bei einer Geocodierung für „Washington“ wird z.B. in der Regel der US-Bundesstaat Washington zurückgegeben:
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "WA",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
},
"location" : {
"lat" : 47.7510741,
"lng" : -120.7401385
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 49.0024442,
"lng" : -116.91558
},
"southwest" : {
"lat" : 45.543541,
"lng" : -124.8489739
}
}
},
"place_id" : "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
"types" : [ "administrative_area_level_1", "political" ]
}
],
"status" : "OK"
}
Wenn jedoch ein bounds
-Argument hinzugefügt wird, das einen Begrenzungsrahmen um den nordöstlichen Teil der USA definiert, führt dies zu diesem Geocode, der die Stadt Washington, D.C. zurückgibt:
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Washington",
"short_name" : "Washington",
"types" : [ "locality", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "District of Columbia",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "District of Columbia",
"short_name" : "DC",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Washington, DC, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
},
"location" : {
"lat" : 38.9071923,
"lng" : -77.03687069999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 38.9958641,
"lng" : -76.90939299999999
},
"southwest" : {
"lat" : 38.7916449,
"lng" : -77.119759
}
}
},
"place_id" : "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Regionsgewichtung
In einer Geocoding-Anfrage können Sie den Geocoding-Dienst mit dem Parameter region
anweisen, nach bestimmten Regionen gewichtete Ergebnisse zurückzugeben. Für diesen Parameter ist ein ccTLD-Argument (Country Code Top-Level Domain) erforderlich, das die Regionsgewichtung angibt. Die meisten ccTLD-Codes sind mit den ISO 3166-1-Codes identisch. Es gibt jedoch einige Ausnahmen. Die ccTLD des Vereinigten Königreichs lautet beispielsweise „uk“ (.co.uk
), der ISO 3166-1-Code ist „gb“ (technisch für die Rechtspersönlichkeit „The United Kingdom of Great Britain and Nordirland“).
Geocoding-Ergebnisse können für jede Domain gewichtet werden, in der die Hauptanwendung von Google Maps offiziell eingeführt wurde. Beachten Sie, dass die Gewichtung Ergebnisse für eine bestimmte Domain nur bevorzugt. Sind relevantere Ergebnisse außerhalb der Domain vorhanden, werden diese möglicherweise auch einbezogen.
Ein Geocode für „Toledo“ gibt beispielsweise dieses Ergebnis zurück, da als Standarddomain für die Geocoding API die USA festgelegt sind. Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Lucas County",
"short_name" : "Lucas County",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Ohio",
"short_name" : "OH",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United States",
"short_name" : "US",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, OH, USA",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
},
"location" : {
"lat" : 41.6639383,
"lng" : -83.55521200000001
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 41.732844,
"lng" : -83.454229
},
"southwest" : {
"lat" : 41.580266,
"lng" : -83.69423700000002
}
}
},
"place_id" : "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Bei einer Geocoding-Anfrage für „Toledo“ mit region=es
(Spanien) wird die spanische Stadt zurückgegeben.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=Toledo®ion=es&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Toledo",
"short_name" : "Toledo",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Toledo",
"short_name" : "TO",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Castile-La Mancha",
"short_name" : "CM",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Toledo, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
},
"location" : {
"lat" : 39.8628316,
"lng" : -4.027323099999999
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 39.88605099999999,
"lng" : -3.9192423
},
"southwest" : {
"lat" : 39.8383676,
"lng" : -4.0796176
}
}
},
"place_id" : "ChIJ8f21C60Lag0R_q11auhbf8Y",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Komponentenfilter
In einer Geocoding-Antwort kann die Geocoding API Adressergebnisse zurückgeben, die auf ein bestimmtes Gebiet beschränkt sind. Sie können die Einschränkung mit dem Filter components
angeben. Ein Filter besteht aus einer Liste von component:value
-Paaren, die durch einen senkrechten Strich (|
) getrennt sind. Filterwerte unterstützen dieselben Methoden zur Rechtschreibkorrektur und teilweisen Abgleich wie bei anderen Geocoding-Anfragen. Wenn der Geocoder eine teilweise Übereinstimmung für einen Komponentenfilter findet, enthält die Antwort das Feld partial_match
.
Folgende components
können gefiltert werden:
postal_code
stimmt mitpostal_code
undpostal_code_prefix
überein.country
gleicht einen Ländernamen oder einen aus 2 Buchstaben bestehenden ISO-3166-1-Ländercode ab. Die API entspricht dem ISO-Standard zur Definition von Ländern. Die Filterung funktioniert am besten, wenn der entsprechende ISO-Code des Landes verwendet wird.
Die folgende components
kann verwendet werden, um die Ergebnisse zu beeinflussen, wird aber nicht erzwungen:
route
entspricht dem langen oder dem Kurznamen einer Route.locality
stimmt mit den Typenlocality
undsublocality
überein.administrative_area
stimmt mit allenadministrative_area
-Ebenen überein.
Hinweise zum Filtern von Komponenten:
- Wiederholen Sie diese Komponentenfilter nicht in Anfragen. Andernfalls gibt die API
Invalid_request
zurück:country
,postal_code
,route
. - Wenn die Anfrage wiederholte Komponentenfilter enthält, wertet die API diese Filter als UND und nicht als ODER aus.
- Die Ergebnisse stimmen mit denen von Google Maps überein, was gelegentlich zu unerwarteten
ZERO_RESULTS
-Antworten führt. Die Verwendung von Place Autocomplete kann in einigen Anwendungsfällen bessere Ergebnisse liefern. Weitere Informationen finden Sie in diesen FAQs. - Geben Sie für jede Adresskomponente diese entweder im Parameter
address
oder in einemcomponents
-Filter an, aber nicht beides. Wenn Sie in beiden die gleichen Werte angeben, wird möglicherweiseZERO_RESULTS
zurückgegeben.
Bei der Geocodierung von „High St, Hastings“ mit components=country:GB
wird das Ergebnis in Hastings, England, und nicht in Hastings-On-Hudson, USA, zurückgegeben.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=high+st+hasting&components=country:GB&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "High Street",
"short_name" : "High St",
"types" : [ "route" ]
},
{
"long_name" : "Hastings",
"short_name" : "Hastings",
"types" : [ "postal_town" ]
},
{
"long_name" : "East Sussex",
"short_name" : "East Sussex",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "England",
"short_name" : "England",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "United Kingdom",
"short_name" : "GB",
"types" : [ "country", "political" ]
},
{
"long_name" : "TN34 3EY",
"short_name" : "TN34 3EY",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "High St, Hastings TN34 3EY, UK",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
},
"location" : {
"lat" : 50.85830319999999,
"lng" : 0.5924594
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 50.8601041,
"lng" : 0.5957329
},
"southwest" : {
"lat" : 50.8559061,
"lng" : 0.5906163
}
}
},
"partial_match" : true,
"place_id" : "ChIJ-Ws929sa30cRKgsMNVkPyws",
"types" : [ "route" ]
}
],
"status" : "OK"
}
Eine Geocoding-Anfrage für den Ort „Santa Cruz“ mit components=country:ES
gibt Santa Cruz de Tenerife auf den Kanarischen Inseln, Spanien, zurück.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "Santa Cruz de Tenerife",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Santa Cruz de Tenerife",
"short_name" : "TF",
"types" : [ "administrative_area_level_2", "political" ]
},
{
"long_name" : "Canary Islands",
"short_name" : "CN",
"types" : [ "administrative_area_level_1", "political" ]
},
{
"long_name" : "Spain",
"short_name" : "ES",
"types" : [ "country", "political" ]
}
],
"formatted_address" : "Santa Cruz de Tenerife, Spain",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
},
"location" : {
"lat" : 28.4636296,
"lng" : -16.2518467
},
"location_type" : "APPROXIMATE",
"viewport" : {
"northeast" : {
"lat" : 28.487616,
"lng" : -16.2356646
},
"southwest" : {
"lat" : 28.4280248,
"lng" : -16.3370045
}
}
},
"place_id" : "ChIJcUElzOzMQQwRLuV30nMUEUM",
"types" : [ "locality", "political" ]
}
],
"status" : "OK"
}
Die Komponentenfilterung gibt nur dann eine ZERO_RESULTS
-Antwort zurück, wenn Sie Filter angeben, die sich gegenseitig ausschließen.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?components=administrative_area:TX|country:FR&key=YOUR_API_KEY
Antwort:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Mit dem Filter components
können Sie gültige Abfragen auch ohne den Adressparameter ausführen. Beim Geocoding einer vollständigen Adresse ist der Parameter address
erforderlich, wenn die Anfrage die Namen und die Anzahl der Gebäude enthält.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Antwort:
{
"results" : [
{
"address_components" : [
{
"long_name" : "Annankatu",
"short_name" : "Annankatu",
"types" : [ "route" ]
},
{
"long_name" : "Helsinki",
"short_name" : "HKI",
"types" : [ "locality", "political" ]
},
{
"long_name" : "Finland",
"short_name" : "FI",
"types" : [ "country", "political" ]
},
{
"long_name" : "00101",
"short_name" : "00101",
"types" : [ "postal_code" ]
}
],
"formatted_address" : "Annankatu, 00101 Helsinki, Finland",
"geometry" : {
"bounds" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
},
"location" : {
"lat" : 60.1657808,
"lng" : 24.938451
},
"location_type" : "GEOMETRIC_CENTER",
"viewport" : {
"northeast" : {
"lat" : 60.168997,
"lng" : 24.9433353
},
"southwest" : {
"lat" : 60.16226160000001,
"lng" : 24.9332897
}
}
},
"place_id" : "ChIJARW7C8sLkkYRgl4je4-RPUM",
"types" : [ "route" ]
}
],
"status" : "OK"
}