Geocoding-Anfrage und -Antwort

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Anfragen

Eine Geocoding API-Anfrage hat das folgende Format:

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

Dabei kann outputFormat einer der folgenden Werte sein:

  • json (empfohlen) gibt die Ausgabe in JSON (JavaScript Object Notation) an oder
  • 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 die Parameter durch kaufmännische Und-Zeichen (&) voneinander getrennt.

Der Rest dieser Seite beschreibt das Geocoding und das umgekehrte Geocoding separat, da für jeden Anfragetyp unterschiedliche Parameter zur Verfügung stehen.

Geocoding-Parameter (Breiten-/Längengradsuche)

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 betreffenden Landes verwendet wird. Vermeiden Sie zusätzliche Adresselemente wie Firmennamen, Wohnungs- und Etagennummern. Adresselemente sollten durch Leerzeichen getrennt werden (in diesem Beispiel als URL mit Maskierung nach %20): 
    address=24%20Sussex%20Drive%20Ottawa%20ON
    Formatieren Sie die Plus Codes wie hier gezeigt (Pluszeichen werden in der URL als %2B und Leerzeichen als Escape-Zeichen in %20 verwendet):
    • Global Code besteht aus vier Zeichen und einem lokalen Code mit mindestens sechs Zeichen (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, in dem die Geocoding-Ergebnisse bevorzugt werden sollen. Dieser Parameter wirkt sich nur auf die Ergebnisse des Geocoders aus und beschränkt diese nicht vollständig. 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. Die unterstützten Sprachen werden häufig von Google aktualisiert. Die Liste ist daher unter Umständen nicht vollständig.
    • Wenn language nicht angegeben ist, versucht der Geocoder, die im Accept-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 Landessprache zurückgegeben und bei Bedarf in ein für den Nutzer lesbares Skript unter Berücksichtigung der bevorzugten Sprache transkribiert. 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 in der bevorzugten Sprache nicht verfügbar ist, verwendet der Geocoder die größte Übereinstimmung.
    • Die bevorzugte Sprache hat einen kleinen Einfluss darauf, welche Ergebnisse die API zurückgibt, sowie in der Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. die Abkürzungen für Straßentypen oder Synonyme, die möglicherweise in einer Sprache gültig sind, in einer anderen aber nicht. Zum Beispiel sind utca und tér Synonyme für Straße und Quadrat auf Ungarisch.
  • region: Der Regionscode als ccTLD-Wert ("top-level domain") mit zwei Zeichen. Dieser Parameter wirkt sich nur auf Ergebnisse des Geocoders aus und beschränkt diese nicht vollständig. Weitere Informationen finden Sie unten im Abschnitt Gewichtung nach Region.
  • components: Ein Komponentenfilter mit durch einen senkrechten Strich (|) getrennten Elementen. 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 im Flag output im Pfad der URL-Anfrage angegeben ist.

In diesem Beispiel fordert die Geocoding API eine json-Antwort auf eine Abfrage der Place ID (ChIJeRpOeF67j4AR9ydy_PIzPuM" an. Dies ist die Place_ID für das Gebäude in 1600 Amphitheatre Parkway, Mountain View, CA.

In dieser Anfrage wird das JSON-Flag output verwendet:

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

In dieser Anfrage wird das XML-Flag output verwendet:

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.

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.
  • "results" enthält ein Array geocodierter Adress- und Geometriedaten.

Im Allgemeinen wird bei der Adresssuche nur ein Eintrag im Array "results" zurückgegeben. Der Geocoder kann jedoch mehrere Ergebnisse zurückgeben, wenn Adressabfragen unklar 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 einem einzigen <GeocodeResponse>-Element und zwei Elementen auf oberster Ebene:

  • <status> enthält Metadaten zur Anfrage. Weitere Informationen finden Sie unter Statuscodes.
  • Null oder mehr <result>-Elemente, die jeweils einen einzelnen Satz geocodierter Adress- und Geometriedaten enthalten.

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, für Ihren Dienst ist aus irgendeinem Grund xml erforderlich. Außerdem muss die Verarbeitung von XML-Strukturen sorgfältig durchgeführt werden, damit Sie auf die richtigen Knoten und Elemente verweisen können. Unter XML mit XPath parsen finden Sie einige empfohlene Designmuster für die Ausgabeverarbeitung.

  • XML-Ergebnisse sind in ein <GeocodeResponse>-Stammelement eingeschlossen.
  • JSON gibt Einträge mit mehreren Elementen über Plural-Arrays (types) an, während XML diese Einträge mit mehreren einzelnen Elementen (<type>) angibt.
  • Leere Elemente werden in JSON durch leere Arrays dargestellt, in XML dagegen durch kein solches Element. 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 sowie möglicherweise Informationen zur Fehlerbehebung, anhand derer Sie herausfinden können, warum das 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 zurückgegeben.
  • "ZERO_RESULTS" gibt an, dass der Geocode erfolgreich war, aber keine Ergebnisse zurückgegeben hat. Dieser Fehler kann auftreten, wenn dem Geocoder ein nicht vorhandenes address übergeben wurde.
  • OVER_DAILY_LIMIT steht für Folgendes:
    • Der API-Schlüssel fehlt oder ist ungültig.
    • Die Abrechnung wurde für Ihr Konto nicht aktiviert.
    • Eine selbst festgelegte Nutzungsbegrenzung wurde überschritten.
    • Die angegebene Zahlungsmethode ist nicht mehr gültig. Das kann z. B. der Fall sein, wenn eine Kreditkarte abgelaufen ist.

    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" zeigt im Allgemeinen an, dass die Abfrage (address, components oder latlng) fehlt.
  • "UNKNOWN_ERROR" gibt an, dass die Anfrage aufgrund eines Serverfehlers nicht verarbeitet werden konnte. Die Anfrage ist möglicherweise erfolgreich, wenn Sie es noch einmal versuchen.

Fehlermeldungen

Wenn der Geocoder einen anderen Statuscode als OK zurückgibt, kann das zusätzliche Feld error_message im Geocoding-Antwortobjekt vorhanden sein. Dieses Feld enthält ausführlichere Informationen zu den Gründen für einen Statuscode.

Ergebnisse

Wenn der Geocoder Ergebnisse zurückgibt, werden diese in einem (JSON-)results-Array platziert. Auch wenn der Geocoder keine Ergebnisse zurückgibt (z. B. wenn die Adresse nicht existiert), gibt er dennoch ein leeres results-Array zurück. 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 den Typ des im Ergebnis zurückgegebenen Merkmals angeben. Beispiel: Der Geocode von „Chicago“ gibt zurück, dass „Chicago“ eine Stadt ist, und gibt außerdem an, dass er eine politische Einheit ist.
  • formatted_address ist ein String mit der für Menschen lesbaren Adresse dieses Standorts.

    Oft entspricht diese Adresse der Postanschrift. In einigen Ländern wie dem Vereinigten Königreich ist die Weitergabe echter Postanschriften aufgrund von Lizenzbeschränkungen nicht zulässig.

    Die formatierte Adresse besteht logisch aus einer oder mehreren Adresskomponenten. Die Adresse & #118; Beispiel: 8th Avenue, New York, NY&#;

    Parsen Sie die formatierte Adresse nicht programmatisch. Verwende stattdessen die einzelnen Adresskomponenten, die in der API-Antwort zusätzlich zum formatierten Adressfeld enthalten sind.

  • address_components[] ist ein Array, das die separaten Komponenten enthält, die für diese Adresse gelten.

    Jede Adresskomponente enthält normalerweise die folgenden Felder:

    • types[] ist ein Array, das den Typ der Adresskomponente angibt. Hier finden Sie eine Liste der unterstützten Typen.
    • long_name ist die vom Geocodierer zurückgegebene vollständige Textbeschreibung oder der Name der Adresskomponente.
    • short_name ist ein abgekürzter Textname für die Adresskomponente, falls verfügbar. Beispielsweise kann eine Adresskomponente für den US-Bundesstaat Alaska den long_name „Alaska" und den short_name der Spalte „AK“ mit der aus zwei Buchstaben bestehenden postalischen Abkürzung haben.

    Beachten Sie die folgenden Fakten zum Array address_components[]:

    • Das Array der Adresskomponenten kann mehr Komponenten als formatted_address enthalten.
    • Das Array enthält nicht unbedingt alle politischen Entitäten, die eine Adresse enthalten. Ausgenommen hiervon sind die im formatted_address enthaltenen. Wenn Sie alle politischen Entitäten abrufen möchten, die eine bestimmte Adresse enthalten, müssen Sie das umgekehrte Geocoding verwenden. Dabei wird der Breitengrad/Längengrad der Adresse als Parameter an die Anfrage übergeben.
    • Es kann nicht garantiert werden, dass das Format der Antwort bei 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. Eine Komponente kann die Position im Array ändern. Der Typ der Komponente kann sich ändern. Eine bestimmte Komponente fehlt möglicherweise in einer späteren Antwort.

    Zur Verarbeitung des Arrays von Komponenten müssen Sie die Antwort parsen und geeignete Werte über Ausdrücke auswählen. Weitere Informationen findest du unter Antworten parsen.

  • postcode_localities[] ist ein Array, das alle Orte in einer Postleitzahl angibt. Dies 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 Breitengrad-/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 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äzise lokalisierten Punkten (z. B. Kreuzungen) interpoliert wurde. Interpolierte Ergebnisse werden in der Regel zurückgegeben, wenn hausnummerngenaue Geocodierungen für eine Adresse in einer Straße nicht zur Verfügung stehen.
      • "GEOMETRIC_CENTER" gibt an, dass das zurückgegebene Ergebnis der geometrische Mittelpunkt eines Ergebnisses ist, z. B. eine Polylinie (z. B. eine Straße) oder ein Polygon (Region).
      • "APPROXIMATE" gibt an, dass das zurückgegebene Ergebnis ein Näherungswert 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. Diese Grenzen stimmen möglicherweise nicht mit dem empfohlenen Darstellungsbereich überein. Beispiel: San Francisco umfasst die Farallon-Inseln, die 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 einen Bereich darstellt: 1/8000th of a degree by 1/8000th of a degree (about 14m x 14m at the Äquator) or less. Plus Codes können auch als Ersatz für Adressen verwendet werden, wenn diese nicht vorhanden sind (Gebäude sind nicht nummeriert oder Straßen nicht benannt).

    Der Plus Code ist als globaler Code und als zusammengesetzter Code formatiert:

    • global_code ist eine vierstellige Vorwahl und ein lokaler oder längerer Code mit mindestens 6 Zeichen (849VCWC8+R9).
    • compound_code ist ein mindestens 6 stelliger lokaler Code mit einem expliziten Standort (CWC8+R9, Mountain View, CA, USA). Parsen Sie diesen Inhalt nicht programmatisch.
    Normalerweise werden sowohl der globale als auch der kombinierte Code zurückgegeben. Wenn sich das Ergebnis jedoch an einem abgelegenen Ort befindet, z. B. in einem Meer oder einer Wüste, kann nur der globale Code zurückgegeben werden.

  • partial_match gibt an, dass der Geocoder keine genaue Übereinstimmung für die ursprüngliche Anfrage zurückgegeben hat, aber teilweise mit der angeforderten Adresse übereinstimmt. Prüfen Sie die ursprüngliche Anfrage auf Rechtschreibfehler und/oder eine unvollständige Adresse.

    Teilübereinstimmungen treten am häufigsten bei Adressen auf, die nicht innerhalb des Orts vorhanden sind, den Sie in der Anfrage angeben. Teilübereinstimmungen können auch zurückgegeben werden, wenn eine Anfrage mit zwei oder mehr Standorten am selben Ort übereinstimmt. So gibt beispielsweise "Hillpar St, Bristol, UK&hl=de eine Teilübereinstimmung für die Henry Street und die Henrietta Street zurück. Wenn eine Anfrage eine falsch geschriebene Adresskomponente enthält, schlägt der Geocoding-Dienst möglicherweise eine alternative Adresse vor. Vorschläge, die auf diese Weise ausgelöst werden, werden auch als Teilü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 Rezensionen von Nutzern abzurufen. Weitere Informationen finden Sie unter Orts-ID.

Arten von Adressen und Adresskomponenten

Das Array types[] im Ergebnis gibt den Adresstyp an. Beispiele für Adressen sind eine Adresse, ein Land oder eine politische Einheit. In address_components[] gibt es außerdem ein types[]-Array, das den Typ der einzelnen Teile der Adresse angibt. Dazu gehören bspw. Hausnummer oder Land. Im Folgenden 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. die Tags political und locality.

Die folgenden Typen werden vom Geocoder sowohl in den Arrays für den Adresstyp als auch in der Art der Adresskomponente unterstützt und zurückgegeben:

  • street_address gibt eine genaue Adresse an.
  • route gibt eine benannte Route an, z. B. "US 101".
  • intersection gibt eine größere Kreuzung an, üblicherweise von zwei Hauptstraßen.
  • political gibt eine politische Einheit an. Dieser Typ gibt in der Regel ein Polygon einer gewissen Verwaltung an.
  • country gibt die nationale politische Einheit an und ist normalerweise der höchste Typ, der vom Geocodierer zurückgegeben wird.
  • administrative_area_level_1 gibt eine erstrangige öffentliche Verwaltungseinheit unterhalb der Länderebene an. Innerhalb der USA sind diese Verwaltungsebenen die Bundesstaaten. Diese Verwaltungsebenen werden nicht von allen Ländern genutzt. In den meisten Fällen entsprechen die Kurznamen „admin_area_level_1“ den ISO 3166-2-Unterteilungen und anderen weit verbreiteten Listen. Dies ist jedoch nicht garantiert, da unsere Geocoding-Ergebnisse auf einer Vielzahl von Signalen und Standortdaten basieren.
  • administrative_area_level_2 gibt eine zweitrangige öffentliche Verwaltungseinheit unterhalb der Länderebene an. Innerhalb der USA sind diese Verwaltungsebenen die Countys. Diese Verwaltungsebenen werden nicht von allen Ländern genutzt.
  • administrative_area_level_3 gibt eine drittrangige öffentliche Verwaltungseinheit unterhalb der Länderebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
  • administrative_area_level_4 gibt eine viertrangige öffentliche Verwaltungseinheit unterhalb der Länderebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
  • administrative_area_level_5 gibt eine fünfte öffentliche Verwaltungseinheit unterhalb der Länderebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
  • administrative_area_level_6 gibt eine sechstrangige öffentliche Verwaltungseinheit unterhalb der Länderebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
  • administrative_area_level_7 gibt eine siebente Organisationseinheit unter der Länderebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen bestehen jedoch nicht in allen Ländern.
  • colloquial_area gibt einen häufig verwendeten alternativen Namen für die Entität an.
  • locality gibt eine politische Stadt oder einen Ort an.
  • sublocality gibt eine erstrangige öffentliche Verwaltungseinheit unterhalb eines Orts an. Für einige Standorte gilt möglicherweise einer der zusätzlichen Typen: sublocality_level_1 bis sublocality_level_5. Jede dieser Ebenen ist eine Verwaltungseinheit. Größere Zahlen geben ein kleineres geografisches Gebiet an.
  • neighborhood gibt ein benanntes Viertel an
  • premise gibt einen benannten Ort an, normalerweise ein Gebäude oder eine Sammlung von Gebäuden mit einem gemeinsamen Namen.
  • subpremise gibt eine erstrangige Entität unterhalb eines benannten Orts an, normalerweise ein einzelnes Gebäude innerhalb eines Gebäudekomplexes mit einem gemeinsamen Namen.
  • plus_code gibt einen codierten Standortverweis an, der aus Breiten- und Längengrad abgeleitet wird. Plus Codes können als Ersatz für Adressen an Orten verwendet werden, an denen sie nicht vorhanden sind (wo Gebäude nicht nummeriert sind oder Straßen nicht benannt sind). Weitere Informationen findest du unter https://plus.codes.
  • postal_code gibt eine Postleitzahl an, die zur Adressierung von Postsendungen innerhalb des Landes verwendet wird.
  • natural_feature weist auf ein bekanntes natürliches Merkmal hin.
  • 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 nicht leicht in eine andere Kategorie einfügen lassen, z. B. an ein Empire State Building oder den Eiffelturm.

Wenn die Liste leer ist, gibt es keine bekannten Typen für die jeweilige Adresskomponente, z. B. Lieu-dit in Frankreich.

Zusätzlich zu den oben genannten Komponenten können Adresskomponenten auch die hier aufgeführten Typen enthalten. Diese Liste ist nicht vollständig und kann sich ändern.

  • floor gibt die Etage 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 zur Orientierung dient.
  • point_of_interest gibt einen benannten POI an.
  • parking gibt einen Parkplatz oder eine Parkstruktur an.
  • post_box gibt einen bestimmten Briefkasten an.
  • postal_town gibt eine Gruppe geografischer Regionen wie locality und sublocality an, die in einigen Ländern für 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 Bus-, Zug- oder öffentlichen Haltestelle an.

Gewichtung nach Darstellungsbereich

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

Der Parameter bounds definiert die Koordinaten für den Breiten- und Längengrad der südwestlichen und nordöstlichen Ecke dieses Markierungsrahmens. Die Koordinaten werden durch einen senkrechten Strich (|) voneinander getrennt.

Ein Geocode für „Washington“ gibt beispielsweise im Allgemeinen 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 Argument bounds 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 mit dem Parameter region anweisen, nach bestimmten Regionen gewichtete Ergebnisse zurückzugeben. Für diesen Parameter wird ein Argument ccTLD (country code top-level domain) verwendet, das die Regionsverzerrung angibt. Die meisten ccTLD-Codes sind bis auf einige Ausnahmen mit den ISO 3166-1-Codes identisch. Die ccTLD für das Vereinigte Königreich lautet beispielsweise „.co.uk“ und der ISO 3166-1-Code lautet „&b“.

Geocoding-Ergebnisse können für alle Domains gewichtet werden, in denen die Google Maps-Hauptanwendung 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 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=AIzaSyCaor12zcAJ3XgISkD8zsoaQ64PAlDgBrs

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

Komponentenfilterung

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 Übereinstimmung 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 entspricht einem Ländernamen oder einem aus zwei Buchstaben bestehenden ISO 3166-1-Ländercode. Die API folgt dem ISO-Standard für die Länderauswahl. Die Filterung funktioniert am besten, wenn der entsprechende ISO-Code des Landes verwendet wird.

Die folgende components kann zur Beeinflussung der Ergebnisse verwendet werden, 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 zum Filtern von Komponenten:

  • Verwenden Sie diese Komponentenfilter nicht in Anfragen. Andernfalls gibt die API Invalid_request zurück: country, postal_code, route.
  • Wenn die Anfrage wiederholt Komponentenfilter enthält, wertet die API diese Filter als AND und nicht als OR aus.
  • Die Ergebnisse stimmen mit Google Maps überein, das gelegentlich unerwartete ZERO_RESULTS-Antworten liefert. Die Verwendung von Place Autocomplete bietet in einigen Anwendungsfällen möglicherweise bessere Ergebnisse. Weitere Informationen finden Sie in diesen FAQs.
  • Geben Sie sie für jede Adresskomponente entweder im address-Parameter oder in einem components-Filter an, aber nicht in beiden. Wenn Sie in beiden dieselben Werte angeben, kann dies zu ZERO_RESULTS führen.

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

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 in Verbindung mit components=country:ES: Santa Cruz de Tenerife auf den Kanarischen Inseln in Spanien.

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 ausführen. Bei der 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"
}