Geocoding-Anfrage und -Antwort

Anfragen

Eine Geocoding API-Anfrage weist folgende Form auf:

https://maps.googleapis.com/maps/api/geocode/outputFormat?parameters

Dabei kann outputFormat einer der folgenden Werte sein:

• json (empfohlen): Zeigt an, dass die Ausgabe in JSON (JavaScript Object Notation) erfolgen soll.
• 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.

Der Rest dieser Seite beschreibt das Geocoding und das umgekehrte Geocoding separat, da für jeden Anfragetyp unterschiedliche Parameter verfügbar sind.

Geocoding-Parameter (Längen- und Breitengradsuche)

Erforderliche Parameter in einer Geocoding-Anfrage:

• address: Die Adresse oder der Plus Code, den Sie geocodieren möchten. Geben Sie Adressen in dem Format an, das vom Postdienst des entsprechenden Landes verwendet wird. Zusätzliche Adresselemente wie Unternehmensname und Wohnungs- oder Wohnungsnummer sollten vermieden werden. Adresselemente sollten durch Leerzeichen voneinander getrennt werden (hier als URL mit Escapezeichen für %20 dargestellt):

  address=24%20Sussex%20Drive%20Ottawa%20ON

  Formatieren Sie hier die Plus Codes, wie hier gezeigt (Pluszeichen werden in %2B mit URL-Escapezeichen und Leerzeichen in %20 mit Escape-Zeichen versehen):
  • Global Code besteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9 ist 849VCWC8%2BR9).
  • Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Standort (CWC8 + R9 Mountain View, CA, USA ist CWC8%2BR9%20Mountain%20View%20CA%20USA).
  
  --OR--
  components: Ein Komponentenfilter mit Elementen, die durch einen senkrechten Strich (|) getrennt sind. Der Komponentenfilter wird auch als optionaler Parameter akzeptiert, wenn ein address angegeben wird. Jedes Element im Komponentenfilter besteht aus einem component:value-Paar und schränkt die Ergebnisse des Geocoders vollständig ein. Weitere Informationen zum Filtern von Komponenten finden Sie unten.
• key: Der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung zum Zweck der Kontingentverwaltung. Schlüssel anfordern

Weitere Informationen finden Sie in den häufig gestellten Fragen.

Optionale Parameter in einer Geocoding-Anfrage:

• bounds: Der Begrenzungsrahmen des Darstellungsbereichs, innerhalb dessen die Geocoding-Ergebnisse bevorzugt werden sollen. Dieser Parameter wirkt sich nur auf die Ergebnisse des Geocoders aus, ohne ihn vollständig einzuschränken. Weitere Informationen finden Sie unten im Abschnitt Gewichtung des Darstellungsbereichs.
• language: Die Sprache, in der die Ergebnisse zurückgegeben werden sollen.
  • Hier finden Sie eine Liste der unterstützten Sprachen. Google aktualisiert die unterstützten Sprachen häufig. Daher ist diese Liste möglicherweise nicht vollständig.
  • Falls language nicht angegeben ist, versucht der Geocoder, die im Header Accept-Language angegebene Sprache oder die Sprache der Domain zu verwenden, aus der die Anfrage gesendet wird.
  • Der Geocoder versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Um dieses Ziel zu erreichen, werden Adressen in der lokalen Sprache zurückgegeben und bei Bedarf unter Berücksichtigung der bevorzugten Sprache in ein für den Nutzer lesbares Skript umgewandelt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die aus der ersten Komponente ausgewählt wird.
  • Wenn ein Name nicht in der bevorzugten Sprache verfügbar ist, verwendet der Geocoder die größte Übereinstimmung.
  • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnismenge, die die API zurückgibt, und in die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen unterschiedlich je nach Sprache, z. B. die Abkürzungen für Straßentypen oder Synonyme, die möglicherweise in einer Sprache gültig sind, aber nicht in einer anderen. Beispiel: utca und tér sind Synonyme für Straße bzw. Quadrat auf Ungarisch.
• region: Der Regionscode als zweistelliger ccTLD-Wert (Top-Level-Domain). Dieser Parameter wirkt sich nur auf die Ergebnisse des Geocoders aus, ohne ihn vollständig einzuschränken. Weitere Informationen finden Sie unter Gewichtung der Regionen weiter unten. Der Parameter kann sich aufgrund geltender Gesetze auch auf Ergebnisse auswirken.
• components: Ein Komponentenfilter, dessen Elemente durch einen senkrechten Strich (|) getrennt werden. Der Komponentenfilter ist erforderlich, wenn die Anfrage kein address enthält. Jedes Element im Komponentenfilter besteht aus einem component: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 wurde, oder standardmäßig im JSON-Format.

In diesem Beispiel fordert die Geocoding API eine json-Antwort für eine Abfrage nach der Orts-ID „ChIJeRpOeF67j4AR9ydy_PIzPuM“ an. Diese Orts-ID steht für das Gebäude in 1600 Amphitheatre Parkway, Mountain View, CA.

Diese Anfrage zeigt die Verwendung des JSON-output-Flags:

https://maps.googleapis.com/maps/api/geocode/json?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

In dieser Anfrage wird die Verwendung des XML-Flags output veranschaulicht:

https://maps.googleapis.com/maps/api/geocode/xml?place_id=ChIJeRpOeF67j4AR9ydy_PIzPuM&key=YOUR_API_KEY

Wählen Sie unten die Tabs aus, um sich die JSON- und XML-Beispielantworten anzusehen.

{
    "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"
}

<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>

Statuscodes

Das Feld "status" im Geocoding-Antwortobjekt enthält den Status der Anfrage sowie möglicherweise Informationen zur Fehlerbehebung, mit deren Hilfe Sie herausfinden können, warum Geocoding nicht funktioniert. Das Feld "status" kann die folgenden Werte enthalten:

• "OK" gibt an, dass keine Fehler aufgetreten sind. Die Adresse wurde erfolgreich geparst und mindestens ein Geocode wurde zurückgegeben.
• "ZERO_RESULTS" gibt an, dass die Geocodierung erfolgreich war, aber keine Ergebnisse zurückgegeben wurden. Dieser Status wird möglicherweise ausgegeben, wenn dem Geocoder ein nicht vorhandenes address-Element übergeben wurde.
• OVER_DAILY_LIMIT gibt Folgendes an:
  • Der API-Schlüssel fehlt oder ist ungültig.
  • Die Abrechnung wurde für Ihr Konto nicht aktiviert.
  • Eine selbst festgelegte Obergrenze für die Nutzung wurde überschritten.
  • Die angegebene Zahlungsmethode ist nicht mehr gültig (z. B. ist eine Kreditkarte abgelaufen).

  Informationen zur Behebung dieses Problems finden Sie in den häufig gestellten Fragen zu 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 oder latlng) 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, gibt es möglicherweise ein zusätzliches error_message-Feld im Geocoding-Antwortobjekt. Dieses Feld enthält ausführlichere Informationen zu den Gründen für den angegebenen Statuscode.

Ergebnisse

Wenn der Geocoder Ergebnisse zurückgibt, werden diese in einem (JSON-)results-Array platziert. Auch wenn der Geocoder keine Ergebnisse zurückgibt, etwa 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, die die im Ergebnis zurückgegebene Featureart identifizieren. Die Geocodierung von „Chicago“ gibt z. B. „Ort“ zurück, was bedeutet, dass „Chicago“ eine Stadt ist, und „political“, was bedeutet, dass Chicago eine politische Einheit ist. Komponenten können ein leeres Array „types“ haben, wenn keine bekannten Typen für diese Adresskomponente vorhanden sind. Die API fügt gegebenenfalls neue Typwerte hinzu. Weitere Informationen finden Sie unter Adresstypen und Adresskomponenten.
• formatted_address ist ein String mit der für Menschen lesbaren Adresse dieses Standorts.

  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 separaten 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 den long_name „Alaska“ und den short_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.

  Zum Verarbeiten des Arrays von Komponenten sollten Sie die Antwort parsen und entsprechende Werte über Ausdrücke auswählen. Weitere Informationen findest du in der Anleitung zum Parsing einer Antwort.

• postcode_localities[] ist ein Array, das alle Orte in einer Postleitzahl angibt. Dieser Wert 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 der normalen Adresssuche ist dieses Feld in der Regel am wichtigsten.

  • location_type speichert zusätzliche Daten zum angegebenen Standort. Die folgenden Werte werden derzeit unterstützt:

    • "ROOFTOP" gibt an, dass das zurückgegebene Ergebnis eine präzise Geocodierung ist, für die 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äzise lokalisierten Punkten (wie z. B. Kreuzungen) interpoliert wurde. Interpolierte Ergebnisse werden üblicherweise dann 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 einer Polylinie (z. B. eine Straße) oder eines Polygons (einer 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 die Ecken southwest und northeast des Markierungsrahmens des Darstellungsbereichs definieren. Im Allgemeinen wird der Darstellungsbereich verwendet, um ein Ergebnis darzustellen, wenn es einem Nutzer angezeigt wird.
  • bounds (optional) enthält den Begrenzungsrahmen, der das zurückgegebene Ergebnis vollständig enthalten kann. Beachten Sie, dass diese Grenzen möglicherweise nicht mit dem empfohlenen Darstellungsbereich übereinstimmen. San Francisco umfasst z. B. 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 Standort, der sich aus Breiten- und Längengraden zusammensetzt und eine Fläche darstellt: 1/8000th eines Grades mal 1/8000th eines Grades (etwa 14 m x 14 m am Äquator) oder kleiner. Plus Codes können als Ersatz für Adressen an Orten verwendet werden, an denen es keine Adressen gibt (wo 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 Code für das Gebiet und einem mindestens sechsstelligen lokalen Code (849VCWC8+R9).
  • compound_code ist ein mindestens 6 Zeichen langer lokaler Code mit einem expliziten Standort (CWC8+R9, Mountain View, CA, USA). Wir raten davon ab, diesen Code programmatisch zu parsen.
  Falls verfügbar, gibt die API sowohl den globalen als auch den zusammengesetzten Code zurück. Wenn das Ergebnis jedoch an einem abgelegenen Ort liegt, z. B. in einem Meer oder einer Wüste, wird möglicherweise nur der globale Code zurückgegeben.

• 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. Du kannst beispielsweise place_id 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 politische Einheit. Außerdem gibt es ein types[]-Array im address_components[], das den Typ der einzelnen Teile der Adresse angibt. Dazu gehören bspw. Hausnummer oder Land. Unten 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 in den Arrays für den Adresstyp als auch im Adresskomponenten 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 bis sublocality_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 wie locality und sublocality 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 und transit_station geben den Standort einer Haltestelle für Bus, Bahn oder ein anderes öffentliches Verkehrsmittel an.

Gewichtung im Darstellungsbereich

In einer Geocoding-Anfrage können Sie den Geocoding-Dienst anweisen, Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) zu bevorzugen. Dazu geben Sie in der Anfrage-URL den Parameter bounds an.

Der Parameter bounds definiert die Breitengrad/Längengrad-Koordinaten der südwestlichen und nordöstlichen Ecke dieses Markierungsrahmens. Die Koordinaten werden durch ein Pipe-Zeichen (|) voneinander getrennt.

Ein Geocode für „Washington“ gibt normalerweise den US-Bundesstaat Washington zurück:

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, ergibt sich dieser 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"
}

Gewichtung nach Region

In einer Geocoding-Anfrage können Sie den Geocoding-Dienst mithilfe des Parameters region anweisen, nach bestimmten Regionen gewichtete Ergebnisse zurückzugeben. Für diesen Parameter wird ein ccTLD-Argument (country code top-level domain) verwendet, das die Regionsgewichtung angibt. Die meisten ccTLD-Codes entsprechen den ISO 3166-1-Codes. Es gibt jedoch einige Ausnahmen. Die ccTLD von United Kingdom ist „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ ist (technisch für die Rechtspersönlichkeit „Vereinigtes Königreich von Großbritannien und Nordirland“).

Geocoding-Ergebnisse können für alle Domains gewichtet werden, in denen die Hauptanwendung von Google Maps offiziell eingeführt wurde. Beachten Sie, dass die Gewichtung Ergebnisse für eine bestimmte Domain nur bevorzugt. Wenn außerhalb der Domain relevantere Ergebnisse vorhanden sind, werden diese möglicherweise einbezogen.

Ein Geocode für „Toledo“ gibt z. B. 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"
}

Eine Geocoding-Anfrage für „Toledo“ mit region=es (Spanien) gibt die spanische Stadt zurück.

Anfrage

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=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 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 senkrechten Strich (|) getrennt sind. Filterwerte unterstützen dieselben Methoden für Rechtschreibkorrektur und teilweise Übereinstimmungen wie andere 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 entspricht postal_code und postal_code_prefix.
• country gleicht einen Ländernamen oder einen aus 2 Buchstaben bestehenden ISO-3166-1-Ländercode ab. Die API folgt dem ISO-Standard für die Definition von Ländern. Die Filterung funktioniert am besten, wenn der entsprechende ISO-Code des Landes verwendet wird.

Der folgende components kann verwendet werden, um Ergebnisse zu beeinflussen, wird aber nicht erzwungen:

• route entspricht dem langen oder kurzen Namen einer Route.
• locality stimmt mit den Typen locality und sublocality überein.
• administrative_area entspricht allen administrative_area-Ebenen.

Hinweise zur Komponentenfilterung:

• 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 AND und nicht als OR aus.
• Die Ergebnisse sind konsistent mit Google Maps, das gelegentlich unerwartete ZERO_RESULTS-Antworten liefert. Die Verwendung von Place Autocomplete bietet in einigen Fällen möglicherweise bessere Ergebnisse. Weitere Informationen finden Sie in diesen FAQs.
• Geben Sie sie für jede Adresskomponente entweder im Parameter address oder in einem components-Filter an, aber nicht in beiden. Wenn Sie für beide dieselben Werte angeben, kann dies zu ZERO_RESULTS führen.

Ein Geocode für „High St, Hastings“ mit components=country:GB liefert ein Ergebnis in Hastings, England, und nicht in Hastings-On-Hudson, USA.

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 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 ohne den Adressparameter erstellen. Bei der Geocodierung 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"
}