Geocoding-Anfrage und -Antwort

Anfrage

Eine Geocoding API-Anfrage hat folgende Form:

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

Dabei kann outputFormat einer der folgenden Werte sein:

• json (empfohlen) verweist auf eine Ausgabe in JSON (JavaScript Object Notation). oder
• xml gibt die Ausgabe in XML an

HTTPS ist erforderlich.

Hinweis: URLs müssen richtig codiert sein, um gültig zu sein. Außerdem sind sie für alle Webdienste auf 16.384 Zeichen beschränkt. Berücksichtigen Sie diese Beschränkung beim Erstellen Ihrer URLs. Verschiedene Browser, Proxys und Server können auch andere Zeichenbeschränkungen für URLs haben.

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.

Geocoding-Parameter (Suche nach Breiten- und Längengrad)

Alle reservierten Zeichen (z. B. das Pluszeichen "+") müssen URL-codiert.

Erforderliche Parameter in einer Geocoding-Anfrage:

• address: die Adresse oder der Plus Code die 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. Elemente der Adresse sollten durch Leerzeichen getrennt werden (hier als URL-Escape-Zeichen zu %20 dargestellt):

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

  Formatieren Sie Plus Codes wie hier gezeigt (Pluszeichen werden in der URL als %2B dargestellt, Leerzeichen als %20):
  • Global Code ist ein vierstelliger Vorwahlbereich mit mindestens 6 Zeichen Ortscode (849VCWC8+R9 ist 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).
  
  --ODER--
  components: Ein Komponentenfilter mit Elementen, die durch einen Pipe (|) getrennt sind. Der Komponentenfilter wird auch als optionaler Parameter akzeptiert, wenn ein address angegeben ist. Jedes Element im Komponentenfilter besteht aus einem component:value-Paar und schränkt die Ergebnisse des Geocoders vollständig ein. Weitere Informationen zu Filtern von Komponenten weiter unten.
• key: Der API-Schlüssel Ihrer Anwendung. Dieser Schlüssel identifiziert Ihre Anwendung für die Kontingentverwaltung. Weitere Informationen zum Abrufen eines Schlüssels

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

Optionale Parameter in einer Geocoding-Anfrage:

• bounds: Der Begrenzungsrahmen des Darstellungsbereichs, innerhalb dessen die Ergebnisse des Geocodings bevorzugt werden sollen. Dieser Parameter wird beeinflussen nur die Ergebnisse des Geocoders, schränken sie aber nicht völlig ein. (Weitere Weitere Informationen zur Gewichtung des Darstellungsbereichs
• language: Die Sprache, in der Ergebnisse zurückgegeben werden sollen.
  • Hier finden Sie eine Liste der unterstützten Sprachen. Google aktualisiert die unterstützten Sprachen häufig. Liste ist unter Umständen nicht vollständig.
  • Wird language nicht angegeben, versucht der Geocoder, Verwenden Sie die bevorzugte Sprache, wie in den Accept-Language-Headers oder in der Muttersprache des Domain, von der die Anfrage gesendet wird.
  • Der Geocoder versucht, eine Adresse anzugeben, die sowohl für Nutzer als auch für Ortsansässige. Um dieses Ziel zu erreichen, gibt Adressen in der Landessprache zurück, transliteriert in eine falls notwendig für den Nutzer lesbar, unter Berücksichtigung der Sprache. Alle anderen Adressen werden in der bevorzugten Sprache. Die 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 Suchergebnisse, und in welcher Reihenfolge sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen unterschiedlich, je nachdem, Abkürzungen wie Abkürzungen für Straßentypen oder Synonyme, die möglicherweise in einer Sprache gültig sein, aber nicht in einer anderen. Beispiel: utca und tér sind im Ungarischen Synonyme für „Straße“ bzw. „Platz“.
• region: der als ccTLD angegebene Regionscode (Top-Level-Domain) aus zwei Zeichen. Durch diesen Parameter wird nur die Ergebnisse des Geocoders beeinflussen, sie aber nicht vollständig einschränken. 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 kein address enthält. Jedes Element im Komponentenfilter besteht aus einem component:value-Paar und schränkt die Ergebnisse vollständig ein vom Geocoder aus. Weitere Informationen zum Filtern von Komponenten finden Sie unten.
• extra_computations: Mit diesem Parameter geben Sie den Parameter folgende zusätzliche Funktionen in der Antwort:
  • ADDRESS_DESCRIPTORS – Siehe Adressdeskriptoren.
  • BUILDING_AND_ENTRANCES: Weitere Informationen finden Sie unter Eingänge und Gebäudeumrisse.
  Wenn Sie mehrere dieser Funktionen für dieselbe API-Anfrage aktivieren möchten, fügen Sie den Parameter extra_computations für jede Funktion in die Anfrage ein. Beispiel:

  extra_computations=ADDRESS_DESCRIPTORS&extra_computations=BUILDING_AND_ENTRANCES

Antworten

Geocoding-Antworten werden in dem Format zurückgegeben, das durch das Flag output angegeben wurde in der URL-Anfrage oder standardmäßig im JSON-Format.

In diesem Beispiel fordert die Geocoding API eine json an. Antwort auf eine Anfrage nach der Adresse "1600 Amphitheatre Parkway, Mountain View, CA“.

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 die Verwendung des XML-Flags output veranschaulicht:

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 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"
                    ]
                },
                {
                    "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 unter Statuscodes unten.
• "results" enthält ein Array geocodierter Adressinformationen und Geometriedaten.

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 unter Statuscodes unten.
• Null oder mehr <result>-Elemente, von denen jedes ein einzelnes Satz geocodierter Adress- und Geometriedaten

Die XML-Antwort ist deutlich länger als die JSON-Antwort. Für Aus diesem Grund empfehlen wir, json als bevorzugte Methode zu verwenden. Ausgabe-Flag, 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. Weitere Informationen finden Sie unter Parsen von XML mit XPath für einige empfohlene Entwurfsmuster für die Ausgabeverarbeitung.

Im weiteren Verlauf dieser Dokumentation wird die JSON-Syntax verwendet. In den meisten Fällen spielt das Ausgabeformat keine Rolle, um Konzepte oder Feldnamen in der Dokumentation zu veranschaulichen. Beachten Sie jedoch Folgendes: kleine Unterschiede:

• XML-Ergebnisse werden in ein Stammelement vom Typ <GeocodeResponse> verpackt.
• In JSON werden Einträge mit mehreren Elementen durch Arrays im Plural (types) gekennzeichnet, in XML hingegen durch mehrere Elemente im Singular (<type>).
• Leere Elemente werden in JSON durch leere Arrays angegeben, in XML einfügen. Eine Antwort, die keine Ergebnisse generiert, gibt ein leeres zurück. results-Array in JSON, aber keine <result>-Elemente in XML .

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 vorhandenes address-Element übergeben wurde.
• OVER_DAILY_LIMIT steht für eines der folgenden Elemente:
  • Der API-Schlüssel fehlt oder ist ungültig.
  • Die Abrechnung ist für Ihr 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 finden Sie in den FAQs zu Google Maps. wie Sie dieses Problem beheben können.

• "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, 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

Gibt der Geocoder einen anderen Statuscode als OK zurück, sind möglicherweise zusätzliche error_message innerhalb des Geocoding-Antwortobjekts. Dieses Feld enthält weitere detaillierte Informationen zu den Gründen für den jeweiligen Statuscode.

Hinweis: Dieses Feld ist nicht immer vorhanden und sein Inhalt kann sich ändern.

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 (etwa wenn die Adresse nicht existiert), wird er gibt ein leeres results-Array zurück. (XML-Antworten bestehen aus null oder mehr <result> elements.)

Ein typisches Ergebnis enthält die folgenden Felder:

• Das Array types[] gibt den Typ der zurückgegebenen Ergebnis. Dieses Array enthält ein Set mit null oder mehr Tags zur Angabe des -Funktion, die im Ergebnis zurückgegeben 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 haben möglicherweise leere Typen Array, wenn keine Typen für diese Adresskomponente vorhanden sind. Die API kann bei Bedarf neue Typwerte hinzufügen. Weitere Informationen finden Sie unter Adresstypen und Adresskomponenten.
• formatted_address ist ein String, der das visuell lesbare Element die 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, die für diese Adresse gelten.

  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.

  Um mit den Komponenten zu arbeiten, sollten Sie die Antwort analysieren und über Ausdrücke die entsprechenden Werte auswählen. Weitere Informationen finden Sie im Leitfaden zur zum Parsen einer Antwort.

• postcode_localities[] ist ein Array mit bis zu 100 Orten. die in einer Postleitzahl enthalten sind. Dieses Element ist nur vorhanden, wenn das Ergebnis eine Postleitzahl ist, zu der mehrere Orte gehören.
• geometry enthält die folgenden Informationen:
  • location enthält die geocodierten Werte für Breiten- und Längengrad. Bei normalen Adressabfragen ist dieses Feld in der Regel das wichtigste.

  • location_type speichert 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 ein -Näherung (normalerweise auf einer Straße), die zwischen zwei präzisen Punkten (wie Kreuzungen) interpoliert wurde Interpolierte Ergebnisse werden in der Regel zurückgegeben, wenn hausnummern-genaue Geocodierungen für eine Straße nicht verfügbar sind. Adresse.
    • "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 der ist eine ungefähre Angabe.
  • viewport enthält den empfohlenen Darstellungsbereich für die Anzeige das zurückgegebene Ergebnis, angegeben in Form von zwei Breitengrad,Längengrad-Werten, die die southwest und northeast Ecke des Begrenzungsrahmens des Darstellungsbereichs. Im Allgemeinen Darstellungsbereich wird verwendet, um ein Ergebnis zu kennzeichnen, wenn es für einen Nutzer angezeigt wird.
  • bounds (optional zurückgegeben) speichert den Begrenzungsrahmen das das zurückgegebene Ergebnis komplett enthalten kann. Die angegebenen Begrenzungen stimmen eventuell nicht mit dem empfohlenen Darstellungsbereich überein. (Beispiel: San Francisco enthält das Feld Farallon-Inseln: technisch gesehen Teil der Stadt sind, aber wahrscheinlich 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 an Orten, an denen keine Adresse existiert (d. h. an Orten, an denen keine Gebäude nummeriert oder Straßen keine Namen haben). Die API gibt nicht immer Plus Codes zurück.

  Wenn der Dienst einen Pluscode 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 sechsstelliger lokaler Code mit einem expliziten Ort (CWC8+R9, Mountain View, CA, USA). Wir raten davon ab, diesen Code programmatisch zu parsen.
  Sofern verfügbar, gibt die API sowohl den globalen als auch den zusammengesetzten Code zurück. Wenn der ausgegebene Ort abgelegen ist und sich etwa im Meer oder in der Wüste befindet, wird vermutlich 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. Sie können z. B. die place_id in einer Places API-Anfrage verwenden, um Details zu einem lokalen Unternehmen wie Telefonnummer, Öffnungszeiten oder Nutzerrezensionen abzurufen. Sehen Sie sich die Orts-ID an. .

Adresstypen und Typen von Adresskomponenten

Das types[]-Array im Ergebnis gibt den Adresstyp an. Beispiele für Adresstypen sind Adressen, ein Land oder eine politische Einheit. Außerdem gibt es im address_components[] ein types[]-Array, 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 der Arrays vom Typ „address type“ und „address component type“:

• 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 können die Adresskomponenten 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.

Hinweis: Die Geocoding API gibt nicht garantiert eine bestimmte Komponente für eine Adresse in unserem Datensatz zurück. Was kann man sich als Stadt, wie z. B. Brooklyn, möglicherweise nicht als Ort, sondern als weitere Komponente angezeigt wird. In diesem Fall sublocality_level_1 angeben. Welche Komponenten zurückgegeben werden, kann sich jederzeit ohne vorherige Ankündigung ändern. Entwerfen Sie Ihren Code flexibel, wenn Sie versuchen, Adresskomponenten aus der Antwort zu extrahieren.

Gewichtung nach Darstellungsbereich

In einer Geocoding-Anfrage können Sie den Geocoding-Dienst so einrichten, dass Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) bevorzugt werden. Sie tun dies in der Anfrage-URL, indem Sie den Parameter bounds festlegen.

Der Parameter bounds definiert die Breiten- und Längengradkoordinaten der Südwest- und Nordostecke dieses Begrenzungsrahmens. Die Koordinaten werden durch ein Pipe-Zeichen (|) getrennt.

Hinweis: Dadurch wird nur eine Voreingenommenheit für Ergebnisse innerhalb des Darstellungsbereichs hinzugefügt. Es ist nicht garantiert, dass alle oder bestimmte Ergebnisse darin enthalten sind. Der Autocomplete-Endpunkt der Places API eignet sich in der Regel besser für mehrdeutige Suchanfragen und kann die Ergebnisse auf einen bestimmten Bereich eingrenzen. Im Artikel Best Practices für das Geocoding finden Sie Informationen dazu, welcher API-Endpunkt für welchen Anwendungsfall am besten geeignet ist.

Ein Geocode für „Washington“ gibt im Allgemeinen den US-Bundesstaat Washington:

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 nordöstlicher Teil der USA führt zu diesem Geocode, der die Stadt Washington, D.C.:

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 anweisen, Ergebnisse, die nach bestimmten Regionen gewichtet sind, mithilfe des region . 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. Beispiel: Die USA Die ccTLD des Königreichs ist „uk“ (.co.uk), während der ISO 3166-1-Code „gb“ ist (technisch für das Rechtssubjekt „The United Kingdom of Great Britain and Nordirland“).

Geocoding-Ergebnisse können für alle Domains gewichtet werden, in denen die wichtigsten Die Google Maps App wurde offiziell eingeführt. 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"
}

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

Anfrage:

https://maps.googleapis.com/maps/api/geocode/json?address=Toledo&region=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 Adresse zurückgeben, Ergebnisse auf einen bestimmten Bereich beschränkt. Sie können die Einschränkung mit dem Filter components angeben. Ein Filter besteht aus einer Liste mit component:value-Paare, die durch ein Pipe-Zeichen (|) voneinander getrennt sind. Filterwerte unterstützen die gleichen Methoden der Rechtschreibkorrektur und teilweisen Übereinstimmung mit anderen Geocoding-Anfragen. Findet der Geocoder eine teilweise Übereinstimmung für eine Komponentenfilter enthält, enthält die Antwort das Feld partial_match.

Zu den components, die gefiltert werden können, gehören:

• postal_code stimmt mit postal_code überein und postal_code_prefix.
• country gleicht einen Ländernamen oder einen aus 2 Buchstaben bestehenden ISO-3166-1-Ländercode ab. Die API entspricht dem ISO-Standard für definiert werden. Die Filterung funktioniert am besten bei Verwendung der ISO-Code des Landes.
  Hinweis: Wenn unerwartete Ergebnisse mit einem Ländercode ausgegeben werden, sollten Sie prüfen, ob Sie einen Code verwenden, der die gewünschten Länder, Außengebiete und besonderen Gebiete von geografischem Interesse umfasst. Informationen zu den Codes finden Sie in der ISO-3166-Ländercodeliste auf Wikipedia oder auf der ISO-Onlinebrowsing-Plattform.

Die folgenden components können verwendet werden, um die Ergebnisse zu beeinflussen, werden aber nicht erzwungen:

• route entspricht dem langen oder Kurznamen einer Route.
• locality Spiele gegen locality und sublocality-Typen.
• administrative_area stimmt mit allen administrative_area Stufen.

Hinweise zum Filtern von Komponenten:

• Wiederholen Sie diese Komponentenfilter nicht in Anfragen, da die API sonst keine Invalid_request: country, postal_code, route
• Wenn die Anfrage wiederholte Komponentenfilter enthält, wertet die API diese aus als AND, nicht als ODER.
• Die Ergebnisse stimmen mit Google Maps überein, sodass gelegentlich unerwartete ZERO_RESULTS-Antworten. Place Autocomplete verwenden kann in einigen Anwendungsfällen bessere Ergebnisse liefern. Weitere Informationen finden Sie unter dieser FAQs.
• Geben Sie jede Adresskomponente entweder im Feld address an Parameter oder in einem components-Filter verwenden, aber nicht beides. Angabe die gleichen Werte in beiden können zu ZERO_RESULTS führen.

Geocode für „Hauptstraße, Hastings“ mit components=country:GB als 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"
}

Die Komponentenfilterung gibt eine ZERO_RESULTS-Antwort zurück. wenn Sie Filter zur Verfügung stellen, 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 ausführen. 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"
}