Anfrage
Eine Geocoding API-Anfrage hat folgende Form:
https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters
Dabei kann outputFormat einen der folgenden Werte haben:
json(empfohlen) gibt die Ausgabe in JSON (JavaScript Object Notation) an. oderxmlgibt die Ausgabe in XML an
HTTPS ist erforderlich.
Einige Parameter sind erforderlich, während andere optional verwendet werden können. Wie in URLs üblich, werden Parameter mit dem Und-Zeichen (&) getrennt.
Im Rest dieser Seite werden Geocoding und umgekehrte Geocodierung getrennt beschrieben, da für jede Anfrageart unterschiedliche Parameter verfügbar sind.
Parameter für die Geocodierung (Breiten-/Längengradsuche)
Erforderliche Parameter in einer Geocodierungsanfrage:
key: Der API-Schlüssel Ihrer Anwendung. Anhand dieses Schlüssels wird Ihre Anwendung zur Kontingentverwaltung identifiziert. Weitere Informationen zum Abrufen eines SchlüsselsSie müssen entweder
addressodercomponentsoder beides in einer Anfrage angeben: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 müssen durch Leerzeichen voneinander getrennt sein (hier als URL-entkommentierte%20dargestellt):address=24%20Sussex%20Drive%20Ottawa%20ON
%2Bdargestellt, Leerzeichen als%20):- Global Code besteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9 wäre beispielsweise
849VCWC8%2BR9). - Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort (CWC8+R9 Mountain View, CA, USA wäre dann
CWC8%2BR9%20Mountain%20View%20CA%20USA).
- Global Code besteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9 wäre beispielsweise
components: Ein Komponentenfilter mit Elementen, die durch ein Pipe (|) getrennt sind. Der Komponentenfilter wird auch als optionaler Parameter akzeptiert, wenn eineaddressangegeben 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.
Weitere Informationen finden Sie in den FAQs.
Optionale Parameter in einer Geocodierungsanfrage:
bounds: Der Begrenzungsrahmen des Darstellungsbereichs, innerhalb dessen die Ergebnisse des Geocodings bevorzugt werden sollen. Durch diesen Parameter werden die Ergebnisse des Geocoders zwar beeinflusst, aber nicht vollständig eingeschränkt. Weitere Informationen finden Sie unten unter Gewichtung des Darstellungsbereichs.language: Die Sprache, in der 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
languagenicht angegeben ist, versucht der Geocoder, die imAccept-Language-Header angegebene bevorzugte Sprache oder die Sprache der Domain zu verwenden, von der die Anfrage gesendet wird. - Der Geocoder gibt sein Bestes, um eine Adresse anzugeben, die sowohl für Nutzer als auch für Einheimische lesbar ist. Dazu werden Straßenadressen in der jeweiligen Landessprache zurückgegeben, die bei Bedarf in ein für den Nutzer lesbares Schriftsystem transkribiert werden, wobei die bevorzugte Sprache berücksichtigt wird. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
- Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet der Geocoder die beste Übereinstimmung.
- 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 aber nicht. Beispiel: utca und tér sind im Ungarischen Synonyme für „Straße“ bzw. „Platz“.
region: der Regionscode, angegeben als zweistelliger Ländercode der Top-Level-Domain (ccTLD) 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 auf die Ergebnisse auswirken, die auf anwendbaren Gesetzen beruhen.components: Ein Komponentenfilter mit Elementen, die durch ein Pipe (|) getrennt sind. Der Komponentenfilter ist erforderlich, wenn die Anfrage keinaddressenthä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.extra_computations: Mit diesem Parameter können Sie die folgenden zusätzlichen Funktionen in der Antwort angeben:ADDRESS_DESCRIPTORS: Weitere Informationen finden Sie unter Adressdeskriptoren.BUILDING_AND_ENTRANCES: Weitere Informationen finden Sie unter Eingänge und Gebäudeumrisse.
extra_computationsfür jede Funktion in die Anfrage ein. Beispiel:extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES
Antworten
Geocoding-Antworten werden im Format zurückgegeben, das durch das output-Flag in der URL-Anfrage angegeben ist, oder standardmäßig im JSON-Format.
In diesem Beispiel fordert die Geocoding API eine json-Antwort für eine Abfrage zur Adresse „1600 Amphitheatre Parkway, Mountain View, CA“ an.
In dieser Anfrage wird das JSON-output-Flag verwendet:
https://maps.googleapis.com/maps/api/geocode/json?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
In dieser Anfrage wird das XML-Flag output verwendet:
https://maps.googleapis.com/maps/api/geocode/xml?address=1600+Amphitheatre+Parkway,+Mountain+View,+CA&key=YOUR_API_KEY
Wählen Sie die Tabs unten aus, um die Beispiel-JSON- und -XML-Antworten aufzurufen.
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" ] }, { "long_name": "1351", "short_name": "1351", "types": [ "postal_code_suffix" ] } ], "formatted_address": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA", "geometry": { "location": { "lat": 37.4222804, "lng": -122.0843428 }, "location_type": "ROOFTOP", "viewport": { "northeast": { "lat": 37.4237349802915, "lng": -122.083183169709 }, "southwest": { "lat": 37.4210370197085, "lng": -122.085881130292 } } }, "place_id": "ChIJRxcAvRO7j4AR6hm6tys8yA8", "plus_code": { "compound_code": "CWC8+W7 Mountain View, CA", "global_code": "849VCWC8+W7" }, "types": [ "street_address" ] } ], "status": "OK" }
Die JSON-Antwort enthält zwei Stammelemente:
"status"enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unten im Abschnitt Statuscodes."results"enthält ein Array mit geocodierten Adress- und Geometrieinformationen.
Bei Adressabfragen wird in der Regel nur ein Eintrag im "results"-Array zurückgegeben. Der Geocoder kann jedoch mehrere Ergebnisse zurückgeben, wenn Adressabfragen mehrdeutig 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 einzelnen <GeocodeResponse> und zwei Elementen der obersten Ebene:
<status>enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unten im Abschnitt Statuscodes.- Null oder mehr
<result>-Elemente, die jeweils einen Satz von geocodierten Adress- und Geometrieinformationen enthalten.
Die XML-Antwort ist deutlich länger als die JSON-Antwort. Aus diesem Grund empfehlen wir, json als bevorzugtes Ausgabeflag zu verwenden, es sei denn, Ihr Dienst erfordert aus irgendeinem Grund xml.
Außerdem ist bei der Verarbeitung von XML-Bäumen Vorsicht geboten, damit Sie auf die richtigen Knoten und Elemente verweisen. Einige empfohlene Designmuster für die Ausgabeverarbeitung finden Sie unter
XML mit XPath parsen.
- XML-Ergebnisse werden in ein Stammelement vom Typ
<GeocodeResponse>verpackt. - In JSON werden Einträge mit mehreren Elementen durch Plural-Arrays (
types) gekennzeichnet, in XML dagegen durch mehrere Elemente im Singular (<type>). - Leere Elemente werden in JSON durch leere Arrays angegeben, in XML jedoch durch das Fehlen eines solchen Elements. Eine Antwort, die keine Ergebnisse generiert, gibt beispielsweise ein leeres
results-Array in JSON, aber keine<result>-Elemente in XML zurück.
Statuscodes
Das Feld "status" im Geocoding-Antwortobjekt enthält den Status der Anfrage und möglicherweise Informationen zur Fehlerbehebung, mit denen Sie herausfinden können, warum das Geocoding 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_LIMITsteht für Folgendes:- Der API-Schlüssel fehlt oder ist ungültig.
- Die Abrechnung ist in Ihrem Konto nicht aktiviert.
- Das von Ihnen festgelegte Nutzungslimit wurde überschritten.
- Die angegebene Zahlungsmethode ist nicht mehr gültig. Das kann z. B. bei einer abgelaufenen Kreditkarte der Fall sein.
Weitere Informationen zur Behebung dieses Problems finden Sie in den häufig gestellten Fragen zu Google Maps.
"OVER_QUERY_LIMIT"zeigt an, dass Sie Ihr Kontingent überschritten haben."REQUEST_DENIED"zeigt an, dass Ihre Anfrage abgelehnt wurde."INVALID_REQUEST"gibt im Allgemeinen an, dass die Anfrage (address,componentsoderlatlng) 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, kann im Geocoding-Antwortobjekt ein zusätzliches Feld error_message vorhanden sein. Dieses Feld enthält genauere Informationen zu den Gründen für den angegebenen Statuscode.
Ergebnisse
Wenn der Geocoder Ergebnisse zurückgibt, fügt er sie in ein (JSON-)results-Array ein. Auch wenn der Geocoder keine Ergebnisse zurückgibt (z. B. wenn 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
types[]-Array gibt den Typ des zurückgegebenen Ergebnisses an. Dieses Array enthält eine Reihe mit null oder mehr Tags, mit denen der Typ des im Ergebnis zurückgegebenen Elements bestimmt wird. Wird der Geocode für Chicago angefordert, wird z. B. ein Element vom Typ „locality“ zurückgegeben, was bedeutet, dass Chicago ein Ort ist, sowie das Element „political“, was bedeutet, dass Chicago eine politische Einheit ist. Komponenten können ein leeres Typenarray haben, 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_addressist ein String, der die Adresse dieses Ortes in visuell 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_nameist die Volltextbeschreibung oder der Name der Adresskomponente, wie vom Geocoder zurückgegeben.short_nameist 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_addressenthalten. - Das Array enthält nicht unbedingt alle politischen Einheiten einer Adresse. Ausgenommen hiervon sind die im
formatted_addressenthaltenen. 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_componentsvariiert 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.
Um mit den Komponenten zu arbeiten, sollten Sie die Antwort analysieren und über Ausdrücke die entsprechenden Werte auswählen. Weitere Informationen finden Sie in der Anleitung zum Parsen einer Antwort.
postcode_localities[]ist ein Array, das bis zu 100 Orte umfasst, die zu einer Postleitzahl gehören. Dieses Element ist nur vorhanden, wenn das Ergebnis eine Postleitzahl ist, zu der mehrere Orte gehören.geometryenthält die folgenden Informationen:locationenthält die geocodierten Werte für Breiten- und Längengrad. Bei normalen Adressabfragen ist dieses Feld in der Regel das wichtigste.location_typespeichert zusätzliche Daten zum angegebenen Ort. Folgende Werte werden derzeit unterstützt:"ROOFTOP"gibt an, dass das zurückgegebene Ergebnis ein genauer Geocode ist, für den wir Standortinformationen bis hin zur genauen Adresse haben."RANGE_INTERPOLATED"gibt an, dass das zurückgegebene Ergebnis eine Schätzung ist (normalerweise auf einer Straße), die anhand von zwei genauen Punkten (wie Kreuzungen) interpoliert wurde. Interpolierte Ergebnisse werden in der Regel zurückgegeben, wenn eine genaue Geocodierung für eine Adresse nicht möglich ist."GEOMETRIC_CENTER"gibt an, dass das zurückgegebene Ergebnis der geometrische Mittelpunkt eines Ergebnisses wie z. B. einer Polylinie (z. B. eine Straße) oder eines Polygons (eine Region) ist."APPROXIMATE"gibt an, dass das zurückgegebene Ergebnis eine Näherung ist.
viewportenthält den empfohlenen Darstellungsbereich für die Anzeige des zurückgegebenen Ergebnisses. Er wird als zwei Werte für Breiten- und Längengrad angegeben, die die Eckensouthwestundnortheastdes Begrenzungsrahmens des Darstellungsbereichs definieren. Im Allgemeinen wird der Darstellungsbereich verwendet, um ein Ergebnis einzurahmen, wenn es einem Nutzer angezeigt wird.bounds(optional) enthält den Begrenzungsrahmen, der das zurückgegebene Ergebnis vollständig umfassen kann. Die angegebenen Begrenzungen stimmen eventuell nicht mit dem empfohlenen Darstellungsbereich überein. San Francisco umfasst z. B. die Farallon-Inseln, die zwar offiziell Teil der Stadt sind, aber nicht im Darstellungsbereich zurückgegeben werden sollten.
-
plus_code(siehe Open Location Code und Plus Codes) ist ein codierter Verweis auf den Standort, der sich aus den Koordinaten (Breiten- und Längengrad) ableiten lässt und einen Bereich definiert: 1/8.000stel eines Grades mal 1/8.000stel eines Grades (ca. 14 m × 14 m am Äquator) oder kleiner. 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. Die API gibt nicht immer Pluscodes zurück.Wenn der Dienst einen Pluscode zurückgibt, wird er als globaler Code und als zusammengesetzter Code formatiert:
global_codebesteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9).compound_codeist 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_matchgibt 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_idist eine eindeutige Kennung, die mit anderen Google APIs verwendet werden kann. Sie können z. B. dieplace_idin einer Places API-Anfrage verwenden, um Details zu einem lokalen Unternehmen wie Telefonnummer, Öffnungszeiten oder Nutzerrezensionen abzurufen. Weitere Informationen finden Sie unter Orts-IDs.
Typen von Adressen und Adresskomponenten
Das types-Array in der Antwort gibt den Adresstyp an. Beispiele für Adresstypen sind eine Privatadresse, ein Land oder eine politische Einheit. Das types-Array im Feld address_component gibt den Typ der einzelnen Teile der Adresse an. Dazu gehören bspw. Hausnummer oder Land.
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 sowohl in den Arrays für Adresstypen als auch in den Arrays für Adresskomponenten unterstützt und zurückgegeben:
| Adresstyp | Beschreibung |
|---|---|
street_address |
Eine genaue Adresse. |
route |
Eine Straße mit einer Bezeichnung, z. B. „B1“. |
intersection |
Eine größere Kreuzung, üblicherweise von zwei Hauptstraßen. |
political |
Eine politische Einheit. Normalerweise zeigt dieser Typ ein Polygon an, das einer öffentlichen Verwaltungseinheit entspricht. |
country |
Die nationale Verwaltungseinheit, in der Regel die der höchsten Ebene. |
administrative_area_level_1 |
Eine öffentliche Verwaltungseinheit eine Stufe unterhalb der Landesebene. In den USA sind diese Verwaltungsebenen 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_1 |
administrative_area_level_2 |
Eine öffentliche Verwaltungseinheit zwei Stufen unterhalb der Landesebene. In den USA sind diese Verwaltungsebenen die Countys. Diese Verwaltungsebenen gibt es nicht in allen Ländern. |
administrative_area_level_3 |
Eine öffentliche Verwaltungseinheit drei Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern. |
administrative_area_level_4 |
Eine öffentliche Verwaltungseinheit vier Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern. |
administrative_area_level_5 |
Eine öffentliche Verwaltungseinheit fünf Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern. |
administrative_area_level_6 |
Eine öffentliche Verwaltungseinheit sechs Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern. |
administrative_area_level_7 |
Eine öffentliche Verwaltungseinheit sieben Stufen unterhalb der Landesebene. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern. |
colloquial_area |
Ein gängiger alternativer Name für die Entität. |
locality |
Eine politische Einheit in Form einer Stadt oder Gemeinde. |
sublocality |
Eine öffentliche Verwaltungseinheit eine Stufe unterhalb des Ortes. Für einige Standorte wird möglicherweise einer der folgenden zusätzlichen Typen ausgegeben: sublocality_level_1 bis sublocality_level_5. Jede dieser Ebenen entspricht einer Verwaltungseinheit. Je höher die Zahl, desto kleiner das geografische Gebiet. |
neighborhood |
Ein benanntes Viertel. |
premise |
Ein benannter Ort, in der Regel ein Gebäude oder ein Komplex von Gebäuden mit einem gemeinsamen Namen. |
subpremise |
Eine adressierbare Entität unterhalb der Standortebene, z. B. eine Wohnung oder ein Appartement. |
plus_code |
Ein codierter Verweis auf den Standort, 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 |
Eine Postleitzahl, wie sie zum Adressieren von Postsendungen innerhalb des Landes verwendet wird. |
natural_feature |
Ein markantes Landschaftsmerkmal. |
airport |
Ein Flughafen. |
park |
Ein benannter Park. |
point_of_interest |
Ein benannter POI. 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 können die Adresskomponenten die unten aufgeführten Typen enthalten.
| Adresskomponententyp | Beschreibung |
|---|---|
floor |
Das Stockwerk einer Gebäudeadresse. |
establishment |
In der Regel ein Ort, der noch nicht kategorisiert wurde. |
landmark |
Ein Ort in der Nähe, der als Referenz zur Orientierung dient. |
point_of_interest |
Ein benannter POI. |
parking |
Ein Parkplatz oder ein Parkhaus. |
post_box |
Einen bestimmten Briefkasten. |
postal_town |
Eine Gruppe geografischer Gebiete wie locality und sublocality, die in einigen Ländern als Postanschriften verwendet werden. |
room |
Der Raum einer Gebäudeadresse. |
street_number |
Die genaue Hausnummer. |
bus_station, train_station und transit_station |
Der Standort einer Bushaltestelle, einer Bahnhaltestelle oder einer Haltestelle des öffentlichen Nahverkehrs. |
Gewichtung des Darstellungsbereichs
In einer Geocoding-Anfrage können Sie den Geocoding-Dienst so einrichten, dass Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) bevorzugt werden. Legen Sie dazu in der Anfrage-URL den Parameter bounds fest.
Der Parameter bounds definiert die Breiten- und Längengradkoordinaten der Südwest- und Nordostecke dieses Begrenzungsrahmens. Die Koordinaten werden durch ein Pipe-Zeichen (|) getrennt.
Bei einer Geocoding-Anfrage für „Washington“ wird normalerweise der US-Bundesstaat Washington zurückgegeben:
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&key=YOUR_API_KEY
Response:
{
"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 Nordosten der USA definiert, wird als Ergebnis des Geocodings die Stadt Washington, D.C. zurückgegeben:
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?address=Washington&bounds=36.47,-84.72%7C43.39,-65.90&key=YOUR_API_KEY
Response:
{
"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"
}
Regionsverzerrung
In einer Geocoding-Anfrage können Sie den Geocoding-Dienst mit dem Parameter region anweisen, Ergebnisse zurückzugeben, die nach Region gewichtet sind. Dieser Parameter nimmt ein ccTLD-Argument (Country Code Top-Level-Domain) an, das die regionale Voreingenommenheit angibt. Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes, mit einigen Ausnahmen. So lautet beispielsweise die ccTLD des Vereinigten Königreichs „uk“ (.co.uk), der ISO 3166-1-Code dagegen „gb“ (technisch für die Entität „Vereinigtes Königreich von Großbritannien und Nordirland“).
Geocoding-Ergebnisse können für alle Domains verzerrt sein, in denen die Google Maps-Anwendung offiziell eingeführt wurde. Beim Anwenden einer Gewichtung werden die Ergebnisse für eine bestimmte Domain lediglich bevorzugt. Sind relevantere Ergebnisse außerhalb der Domain verfügbar, werden sie voraussichtlich ebenfalls einbezogen.
Bei der Geocodierung von „Toledo“ erhalten Sie z. B. folgendes Ergebnis, weil 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
Response:
{
"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
Response:
{
"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 einen bestimmten Bereich 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 Pipe (|) getrennt sind. Bei den Filterwerten werden dieselben Methoden zur Rechtschreibkorrektur und zur teilweisen Übereinstimmung wie bei anderen Geocoding-Anfragen unterstützt. Wenn der Geocoder eine teilweise Übereinstimmung für einen Komponentenfilter findet, enthält die Antwort ein partial_match-Feld.
Folgende components können gefiltert werden:
postal_codeentsprichtpostal_codeundpostal_code_prefix.countrygleicht einen Ländernamen oder einen aus 2 Buchstaben bestehenden ISO-3166-1-Ländercode ab. Die API berücksichtigt den ISO-Standard für die Definition von Ländern. Die Filterung funktioniert am besten, wenn der entsprechende ISO-Code des Landes verwendet wird.
Die folgenden components können verwendet werden, um die Ergebnisse zu beeinflussen, werden aber nicht erzwungen:
routegleicht dem langen oder dem Kurznamen einer Route ab.localitysucht nach einer Übereinstimmung mit den Typenlocalityundsublocality.administrative_areagleicht alle Ebenen desadministrative_areaab.
Hinweise zum Filtern von Komponenten:
- Wiederholen Sie diese Komponentenfilter nicht in Anfragen, da die API andernfalls
Invalid_requestzurückgibt:country,postal_code,route. - Wenn die Anfrage wiederholte Komponentenfilter enthält, werden diese von der API als UND- und nicht als ODER-Bedingung ausgewertet.
- Die Ergebnisse stimmen mit Google Maps überein, was gelegentlich zu unerwarteten
ZERO_RESULTS-Antworten führt. In einigen Fällen kann die Verwendung von Place Autocomplete bessere Ergebnisse liefern. Weitere Informationen finden Sie in diesen FAQs. - Geben Sie jede Adresskomponente entweder im Parameter
addressoder in einemcomponents-Filter an, aber nicht in beiden. Wenn Sie in beiden Feldern dieselben Werte angeben, kann das zuZERO_RESULTSführen.
Bei der Geocodierung von „High St, Hastings“ mit components=country:GB wird ein 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
Response:
{
"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"
}
Bei einer Geocode-Anfrage für die Ortschaft „Santa Cruz“ mit components=country:ES wird Santa Cruz de Tenerife auf den Kanarischen Inseln in Spanien zurückgegeben.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?components=locality:santa+cruz|country:ES&key=YOUR_API_KEY
Response:
{
"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"
}
Beim Komponentenfiltern wird nur dann eine ZERO_RESULTS-Antwort zurückgegeben, 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
Response:
{
"results" : [],
"status" : "ZERO_RESULTS"
}
Mit dem Filter components können Sie gültige Abfragen ohne den Adressparameter stellen. Beim Geocodieren einer vollständigen Adresse ist der Parameter address erforderlich, wenn die Anfrage die Namen und Nummern von Gebäuden enthält.
Anfrage:
https://maps.googleapis.com/maps/api/geocode/json?components=route:Annankatu|administrative_area:Helsinki|country:Finland&key=YOUR_API_KEY
Response:
{
"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"
}