„Geocoding“-Dienst

Übersicht

Beim Geocoding werden Adressen wie „1600 Amphitheatre Parkway, Mountain View, CA, USA“ in geografische Koordinaten (Breitengrad 37.423021 und Längengrad -122.083739) umgewandelt. Anhand dieser Koordinaten können Sie dann Markierungen setzen oder die Karte positionieren.

Bei der umgekehrten Geocodierung werden geografische Koordinaten in eine visuell lesbare Adresse umgewandelt. Weitere Informationen hierzu finden Sie unter Umgekehrte Geocodierung (Adresssuche).

Sie können über den Geocoder auch die Adresse für eine bestimmte Orts-ID ermitteln.

Die Maps JavaScript API bietet eine Geocoder-Klasse für das dynamische Geocoding und die dynamische umgekehrte Geocodierung anhand von Nutzereingaben. Wenn Sie stattdessen statische, bekannte Adressen geocodieren möchten, können Sie den Webdienst für die Geocodierung nutzen.

Erste Schritte

Bevor Sie den Geocoding-Dienst in der Maps JavaScript API verwenden können, müssen Sie die Geocoding API in der Google Cloud Console in dem Projekt aktivieren, das Sie für die Maps JavaScript API eingerichtet haben.

So öffnen Sie die Liste der aktivierten APIs:

1. Rufen Sie die Google Cloud Console auf.
2. Klicken Sie auf die Schaltfläche Projekt auswählen, wählen Sie das Projekt aus, das Sie für die Maps JavaScript API eingerichtet haben, und klicken Sie dann auf Öffnen.
3. Suchen Sie im Dashboard in der Liste der APIs nach Geocoding API.
4. Wenn die API in der Liste angezeigt wird, müssen Sie nichts weiter tun. Ist die API nicht aufgeführt, aktivieren Sie sie:
   1. Wählen Sie oben auf der Seite API AKTIVIEREN aus, um den Tab Bibliothek aufzurufen. Sie haben auch die Möglichkeit, im Menü auf der linken Seite Bibliothek auszuwählen.
   2. Suchen Sie nach der Geocoding API und wählen Sie sie dann in der Ergebnisliste aus.
   3. Klicken Sie auf AKTIVIEREN. Die Geocoding API wird dann in der Liste der APIs auf dem Dashboard angezeigt.

Preise und Richtlinien

Preise

Seit 16. Juli 2018 gilt für Maps, Routes und Places ein neues nutzungsorientiertes Preismodell (Pay as you go). Weitere Informationen zu den aktuellen Preisen und Nutzungslimits für die Verwendung des JavaScript-Geocoding-Dienstes finden Sie unter Nutzung und Abrechnung für die Geocoding API.

Richtlinien

Die Nutzung des Geocoding-Dienstes muss den Richtlinien für die Geocoding API entsprechen.

Geocoding-Anfragen

Der Zugriff auf den Geocoding-Dienst erfolgt asynchron, da dazu der Aufruf eines externen Servers über die Google Maps API erforderlich ist. Daher muss eine Callback-Methode übergeben werden, die nach Abschluss der Anfrage ausgeführt wird. Das Ergebnis wird dann über die Callback-Methode verarbeitet. Über den Geocoder werden möglicherweise mehrere Ergebnisse zurückgegeben.

Sie können innerhalb Ihres Codes über das google.maps.Geocoder-Konstruktorobjekt auf den Geocodierungsdienst der Google Maps API zugreifen. Durch die Geocoder.geocode()-Methode wird eine Anfrage an den Geocodierungsdienst initiiert. Dazu wird ein GeocoderRequest-Objektliteral übergeben, das die Eingabebedingungen und eine Callback-Methode enthält, die nach dem Empfang der Antwort ausgeführt werden soll.

Das GeocoderRequest-Objektliteral enthält die folgenden Felder:

{
 address: string,
 location: LatLng,
 placeId: string,
 bounds: LatLngBounds,
 componentRestrictions: GeocoderComponentRestrictions,
 region: string
}

Erforderliche Parameter: Sie müssen genau eines der folgenden Felder angeben:

• address: die Adresse, die Sie geocodieren möchten
       oder
  location: das LatLng-Element (oder LatLngLiteral-Element), für das die am nächsten liegende Adresse in visuell lesbarer Form ausgegeben wird. Vom Geocoder wird eine umgekehrte Geocodierung ausgeführt. Weitere Informationen zur umgekehrten Geocodierung
       oder
  placeId: die Orts-ID des Ortes, für den die am nächsten liegende Adresse in visuell lesbarer Form ausgegeben werden soll. Weitere Informationen dazu, wie Sie eine Adresse für eine Orts-ID abrufen

Optionale Parameter:

• bounds: der LatLngBounds-Wert, innerhalb dessen die Ergebnisse des Geocodings bevorzugt werden sollen. Durch den bounds-Parameter werden die Ergebnisse des Geocoders zwar beeinflusst, aber nicht vollständig eingeschränkt. Weitere Informationen zur Gewichtung des Darstellungsbereichs finden Sie unten.
• componentRestrictions: wird verwendet, um die Ergebnisse auf einen bestimmten Bereich einzugrenzen. Weitere Informationen zum Filtern von Komponenten finden Sie unten.
• region: der Regionscode, angegeben als zweistelliges (nicht numerisches) untergeordnetes Unicode-Tag für Regionen. In den meisten Fällen sind diese Tags direkt dem zweistelligen Ländercode der Top-Level-Domain (ccTLD) zugeordnet. Durch den region-Parameter werden die Ergebnisse des Geocoders zwar beeinflusst, aber nicht vollständig eingeschränkt. Weitere Informationen zur Gewichtung nach Regionscode finden Sie unten.
• extraComputations: Der einzige zulässige Wert für diesen Parameter ist ADDRESS_DESCRIPTORS. Weitere Informationen finden Sie unter Adressenbeschreibungen.
• fulfillOnZeroResults: Erfülle die Zusicherung bei einem Status „ZERO_RESULT“ in der Antwort. Das kann sinnvoll sein, da auch bei null Geocoding-Ergebnissen möglicherweise zusätzliche Felder auf Antwortebene zurückgegeben werden. Weitere Informationen finden Sie unter Auftrag bei Nullergebnissen ausführen.

Geocoding-Antworten

Für den Geocoding-Dienst ist eine Callback-Methode erforderlich, die nach dem Abrufen der Geocoder-Ergebnisse ausgeführt wird. Bei diesem Callback sollten 2 Parameter weitergegeben werden, die einen results- und einen status-Code enthalten, und zwar in dieser Reihenfolge.

Geocoding-Ergebnisse

Das GeocoderResult-Objekt steht für ein einzelnes Geocoding-Ergebnis. Bei einer Geocode-Anfrage werden möglicherweise mehrere Ergebnisobjekte zurückgegeben:

results[]: {
 types[]: string,
 formatted_address: string,
 address_components[]: {
   short_name: string,
   long_name: string,
   postcode_localities[]: string,
   types[]: string
 },
 partial_match: boolean,
 place_id: string,
 postcode_localities[]: string,
 geometry: {
   location: LatLng,
   location_type: GeocoderLocationType
   viewport: LatLngBounds,
   bounds: LatLngBounds
 }
}

Diese Felder werden im Folgenden beschrieben:

• types[] ist ein Array, das den Adresstyp des zurückgegebenen Ergebnisses angibt. Dieses Array enthält eine Reihe mit keinem oder mehreren Tags, mit denen der Typ des im Ergebnis zurückgegebenen Elements bestimmt wird. Bei der Anfrage nach dem Geocode für Chicago wird z. B. einerseits ein Element vom Typ „locality“ zurückgegeben, was bedeutet, dass Chicago eine Stadt ist, andererseits auch das Element „political“, was bedeutet, dass Chicago eine politische Einheit ist. Weitere Informationen zu Typen von Adressen und Adresskomponenten finden Sie unten.
• formatted_address ist ein String, der die Adresse dieses Ortes in lesbarer Form enthält.

  Diese Adresse stimmt häufig mit der Postanschrift überein. In einigen Ländern, z. B. dem Vereinigten Königreich, ist die Weitergabe echter Postanschriften aufgrund von Lizenzeinschränkungen nicht zulässig.

  Die formatierte Adresse besteht aus einer oder mehreren Adresskomponenten. Die Adresse „111 8th Avenue, New York, NY“ besteht z. B. aus den folgenden Komponenten: „111“ (Hausnummer), „8th Avenue“ (Straße), „New York“ (Stadt) und „NY“ (US-Bundesstaat).

  Wir raten davon ab, die formatierte Adresse programmatisch zu parsen. Verwenden Sie stattdessen die einzelnen Adresskomponenten, die zusätzlich zur formatierten Adresse in der API-Antwort enthalten sind.

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

  Jede Adresskomponente enthält normalerweise die folgenden Felder:

  • types[] ist ein Array, das den Typ der Adresskomponente angibt. Sehen Sie sich die Liste der unterstützten Typen an.
  • long_name ist die Volltextbeschreibung oder der Name der Adresskomponente, wie vom Geocoder zurückgegeben.
  • short_name ist ein abgekürzter Textname für die Adresskomponente, falls vorhanden. Beispielsweise könnte eine Adresskomponente für den US-Bundesstaat Alaska 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.

  Weitere Informationen zu Typen von Adressen und Adresskomponenten finden Sie unten.

• 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 für einen Ort, die mit anderen Google APIs verwendet werden kann. Sie können z. B. die place_id mit der Google Places API-Bibliothek verwenden, um Details zu einem lokalen Unternehmen wie Telefonnummer, Öffnungszeiten oder Nutzerrezensionen abzurufen. Weitere Informationen finden Sie in der Übersicht zur Orts-ID.
• postcode_localities[] ist ein Array, das alle Orte umfasst, die zu einer Postleitzahl gehören. Dieses Element ist nur vorhanden, wenn das Ergebnis eine Postleitzahl ist, zu der mehrere Orte gehören.

• geometry enthält die folgenden Informationen:

  • location enthält die geocodierten Werte für Breiten- und Längengrad. Der entsprechende Ort wird als LatLng-Objekt zurückgegeben und nicht als formatierter String.
  • location_type enthält zusätzliche Daten zum angegebenen Ort. Folgende Werte werden derzeit unterstützt:
    • ROOFTOP gibt an, dass das zurückgegebene Ergebnis genau geocodiert werden konnte.
    • RANGE_INTERPOLATED gibt an, dass das zurückgegebene Ergebnis eine Schätzung ist (normalerweise auf einer Straße), die anhand von zwei genauen Punkten (wie Kreuzungen) interpoliert wurde. Interpolierte Ergebnisse werden in der Regel zurückgegeben, wenn eine genaue Geocodierung für eine Adresse nicht möglich ist.
    • GEOMETRIC_CENTER gibt an, dass das zurückgegebene Ergebnis der geometrische Mittelpunkt eines Ergebnisses wie z. B. einer Polylinie (z. B. eine Straße) oder eines Polygons (eine Region) ist.
    • APPROXIMATE gibt an, dass das zurückgegebene Ergebnis eine Näherung ist.
  
  
  • viewport gibt den empfohlenen Darstellungsbereich für das zurückgegebene Ergebnis an.
  • bounds (optional) enthält den LatLngBounds-Wert, der das zurückgegebene Ergebnis vollständig umfassen kann. Die angegebenen Begrenzungen stimmen eventuell nicht mit dem empfohlenen Darstellungsbereich überein. San Francisco umfasst z. B. die Farallon-Inseln, die zwar offiziell Teil der Stadt sind, aber nicht im Darstellungsbereich zurückgegeben werden sollten.

Die Adressen werden vom Geocoder in der im Browser festgelegten Sprache oder in der Sprache zurückgegeben, die Sie beim Laden des API-JavaScript-Codes mit dem language-Parameter festgelegt haben. Weitere Informationen finden Sie unter Lokalisierung.

Typen von Adressen und Adresskomponenten

Das types[]-Array im GeocoderResult definiert den Adresstyp. Das types[]-Array kann auch innerhalb einer GeocoderAddressComponent zurückgegeben werden, wodurch der Typ der jeweiligen Adresskomponente angegeben wird. Vom Geocoder zurückgegebene Adressen umfassen evtl. mehrere Typen, die als Tags betrachtet werden können. Viele Städte haben z. B. Tags vom Typ political und locality.

Die folgenden Typen werden vom Geocoder sowohl als Adresstypen als auch als Adresskomponenten unterstützt und zurückgegeben:

• street_address gibt eine genaue Adresse an.
• route gibt eine Straße mit einer Bezeichnung an, z. B. „B1“.
• intersection gibt eine größere Kreuzung, üblicherweise von 2 Hauptstraßen an.
• political gibt eine politische Einheit an. Dieser Typ stellt meistens ein Polygon einer öffentlichen Einrichtung dar.
• country gibt eine staatliche politische Einheit (Land) an und ist normalerweise der Typ mit dem höchsten Rang, der vom Geocoder zurückgegeben wird.
• administrative_area_level_1 gibt eine öffentliche Verwaltungseinheit 1 Stufe unterhalb der Landesebene an. In den USA sind diese Verwaltungsebenen z. B. die Bundesstaaten. Diese Verwaltungsebenen gibt es nicht in allen Ländern. In den meisten Fällen sind Kurzbezeichnungen dieses Typs eng an die Untereinheiten des Standards ISO 3166-2 und andere gängige Definitionen angelehnt. Eine Garantie hierfür können wir jedoch nicht geben, da unsere Geocoding-Ergebnisse auf verschiedenen Signalen und Standortdaten basieren.
• administrative_area_level_2 gibt eine öffentliche Verwaltungseinheit 2 Stufen unterhalb der Landesebene an. In den USA sind diese Verwaltungsebenen z. B. die Countys. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
• administrative_area_level_3 gibt eine öffentliche Verwaltungseinheit 3 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
• administrative_area_level_4 gibt eine öffentliche Verwaltungseinheit 4 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
• administrative_area_level_5 gibt eine öffentliche Verwaltungseinheit 5 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
• administrative_area_level_6 gibt eine öffentliche Verwaltungseinheit 6 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
• administrative_area_level_7 gibt eine öffentliche Verwaltungseinheit 7 Stufen unterhalb der Landesebene an. Dieser Typ steht für eine kleine Verwaltungseinheit von geringerer Bedeutung. Diese Verwaltungsebenen gibt es nicht in allen Ländern.
• colloquial_area gibt eine gängige alternative Bezeichnung für die Einheit an.
• locality gibt die politische Einheit einer Stadt oder Gemeinde an.
• sublocality gibt eine öffentliche Verwaltungseinheit eine Stufe unterhalb des Ortes an. Für einige Standorte wird möglicherweise einer der folgenden zusätzlichen Typen ausgegeben: sublocality_level_1 bis sublocality_level_5. Jede dieser Ebenen entspricht einer Verwaltungseinheit. Je höher die Zahl, desto kleiner das geografische Gebiet.
• neighborhood gibt ein benanntes Viertel an.
• premise gibt einen benannten Ort an, normalerweise ein Gebäude oder einen Komplex von Gebäuden mit einem gemeinsamen Namen.
• subpremise gibt eine adressierbare Entität unterhalb der Standortebene an, z. B. eine Wohnung, eine Einheit oder eine Suite.
• 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 folgenden Typen enthalten.

Hinweis: 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.

Statuscodes

Der status-Code gibt einen der folgenden Werte zurück:

• "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 wird möglicherweise ausgegeben, wenn dem Geocoder ein nicht vorhandenes address-Element übergeben wurde.
• "OVER_QUERY_LIMIT" gibt an, dass Sie Ihr Kontingent überschritten haben.
• "REQUEST_DENIED" gibt an, dass Ihre Anfrage abgelehnt wurde. Die Webseite ist nicht dazu berechtigt, den Geocoder zu verwenden.
• "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.
• "ERROR" gibt an, dass das Zeitlimit für die Anfrage überschritten wurde oder dass ein Problem beim Kontaktieren der Google-Server aufgetreten ist. Möglicherweise ist die Anfrage erfolgreich, wenn Sie es noch einmal versuchen.

Im folgenden Beispiel wird eine Adresse geocodiert und eine Markierung bei den zurückgegebenen Breiten- und Längengradwerten gesetzt. Der Handler wird als anonymes Funktionsliteral weitergegeben.

  var geocoder;
  var map;
  function initialize() {
    geocoder = new google.maps.Geocoder();
    var latlng = new google.maps.LatLng(-34.397, 150.644);
    var mapOptions = {
      zoom: 8,
      center: latlng
    }
    map = new google.maps.Map(document.getElementById('map'), mapOptions);
  }

  function codeAddress() {
    var address = document.getElementById('address').value;
    geocoder.geocode( { 'address': address}, function(results, status) {
      if (status == 'OK') {
        map.setCenter(results[0].geometry.location);
        var marker = new google.maps.Marker({
            map: map,
            position: results[0].geometry.location
        });
      } else {
        alert('Geocode was not successful for the following reason: ' + status);
      }
    });
  }

<body onload="initialize()">
 <div id="map" style="width: 320px; height: 480px;"></div>
  <div>
    <input id="address" type="textbox" value="Sydney, NSW">
    <input type="button" value="Encode" onclick="codeAddress()">
  </div>
</body>

Beispiel ansehen

Gewichtung des Darstellungsbereichs

Sie können den Geocoding-Dienst auch so einrichten, dass Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) bevorzugt werden. Dazu definieren Sie über den bounds-Parameter innerhalb des GeocoderRequest-Objektliterals die Grenzen des Darstellungsbereichs. Beim Anwenden einer Gewichtung werden die Ergebnisse innerhalb der Begrenzungen lediglich bevorzugt. Sind relevantere Ergebnisse außerhalb der Begrenzungen verfügbar, werden sie voraussichtlich ebenfalls einbezogen.

Bei einer Geocoding-Anfrage für „Winnetka“ wird normalerweise diesen Vorort von Chicago zurückgegeben:

{
  "types":["locality","political"],
  "formatted_address":"Winnetka, IL, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["locality","political"]
  },{
    "long_name":"Illinois",
    "short_name":"IL",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "geometry":{
    "location":[ -87.7417070, 42.1083080],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJW8Va5TnED4gRY91Ng47qy3Q"
}

Wenn jedoch ein bounds-Parameter angegeben wird, der einen Begrenzungsrahmen für das San Fernando-Tal in Los Angeles definiert, wird als Ergebnis des Geocodings der Stadtteil „Winnetka“ im entsprechenden Rahmen zurückgegeben:

{
  "types":["sublocality","political"],
  "formatted_address":"Winnetka, California, USA",
  "address_components":[{
    "long_name":"Winnetka",
    "short_name":"Winnetka",
    "types":["sublocality","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "types":["administrative_area_level_3","political"]
  },{
    "long_name":"Los Angeles",
    "short_name":"Los Angeles",
    "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"]
  }],
  "geometry":{
    "location": [34.213171,-118.571022],
    "location_type":"APPROXIMATE"
  },
  "place_id": "ChIJ0fd4S_KbwoAR2hRDrsr3HmQ"
}

Gewichtung nach Regionscode

Sie können auch mit dem region-Parameter festlegen, dass der Geocoding-Dienst nach bestimmten Regionen gewichtete Ergebnisse liefert. Der Parameter entspricht dem Regionscode, angegeben als zweistelliges (nicht numerisches) untergeordnetes Unicode-Tag für Regionen. Diese Tags sind direkt dem zweistelligen Ländercode der Top-Level-Domain (ccTLD) zugeordnet, z. B. „uk“ in „co.uk“. In einigen Fällen unterstützt das region-Tag auch ISO-3166-1-Codes, die sich teilweise von den ccTLD-Werten unterscheiden, z. B. „GB“ für Großbritannien.

Wenn Sie den region-Parameter verwenden:

• Geben Sie nur ein Land oder eine Region an. Zusätzliche Werte werden ignoriert und können dazu führen, dass die Anfrage fehlschlägt.
• Verwenden Sie nur zweistellige untergeordnete Tags für Regionen (Unicode-CLDR-Format). Alle anderen Eingaben führen zu Fehlern.
• Es werden nur die Länder und Regionen unterstützt, die in den Details zur Google Maps Platform-Abdeckung aufgeführt sind.

Geocoding-Anfragen können für alle Domains gesendet werden, in denen das Geocoding über die Google Maps-Anwendung angeboten wird. 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 den Geocoding-Dienst die USA festgelegt sind:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, OH, USA",
  "address_components":[{
    "long_name":"Toledo",
    "short_name":"Toledo",
    "types":["locality","political"]
  },{
    "long_name":"Ohio",
    "short_name":"OH",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"United States",
    "short_name":"US",
    "types":["country","political"]
  }],
  "place_id": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw"
}

Wenn dagegen das Feld region auf 'es' (Spanien) eingestellt ist, wird bei der Geocodierung von „Toledo“ die gleichnamige spanische Stadt zurückgegeben:

{
  "types":["locality","political"],
  "formatted_address":"Toledo, España",
  "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":"Castilla-La Mancha",
    "short_name":"CM",
    "types":["administrative_area_level_1","political"]
  },{
    "long_name":"España",
    "short_name":"ES",
    "types":["country","political"]
  }],
  "place_id": "ChIJ8f21C60Lag0R_q11auhbf8Y"
}

Filtern von Komponenten

Sie können mit einem Komponentenfilter festlegen, dass der Geocoding-Dienst nur Adressergebnisse zurückgibt, die auf einen bestimmten Bereich beschränkt sind. Definieren Sie den Filter im componentRestrictions-Parameter. Bei den Filterwerten werden dieselben Methoden zur Rechtschreibkorrektur und zur teilweisen Übereinstimmung wie bei anderen Geocoding-Anfragen unterstützt.

Über den Geocoder werden nur die Ergebnisse zurückgegeben, die mit allen Komponentenfiltern übereinstimmen. Das heißt, die Filter werden mit einer UND- und nicht mit einer ODER-Bedingung verknüpft.

Ein Komponentenfilter besteht aus mindestens einem der folgenden Elemente:

• route gleicht den langen oder den Kurznamen einer Route ab.
• locality sucht nach einer Übereinstimmung mit den Typen „locality“ und „sublocality“.
• administrativeArea gleicht alle Ebenen des Verwaltungsgebiets ab.
• postalCode sucht nach einer Übereinstimmung mit Postleitzahlen und Präfixen von Postleitzahlen.
• country gleicht einen Ländernamen oder einen aus 2 Buchstaben bestehenden ISO-3166-1-Ländercode ab. Hinweis: Die API berücksichtigt den ISO-Standard für die Definition von Ländern. Die Filterung funktioniert am besten, wenn der entsprechende ISO-Code des Landes verwendet wird.

Im folgenden Beispiel sehen Sie, wie der componentRestrictions-Parameter zum Filtern nach country und postalCode genutzt wird:

function codeAddress() {
geocoder.geocode({
  componentRestrictions: {
    country: 'AU',
    postalCode: '2000'
  }
}, function(results, status) {
  if (status == 'OK') {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  } else {
    window.alert('Geocode was not successful for the following reason: ' + status);
  }
});
}

Bei Nullergebnissen ausliefern

Bei der umgekehrten Geocodierung wird die Zusicherung standardmäßig bei status=ZERO_RESULTS gebrochen. Die zusätzlichen Felder auf Antwortebene plus_code und address_descriptor können in diesem Fall jedoch trotzdem ausgefüllt werden. Wenn für den Parameter fulfillOnZeroResults „true“ angegeben wird, wird das Versprechen nicht gebrochen und auf diese zusätzlichen Felder kann über das Versprechen zugegriffen werden, sofern vorhanden.

Im folgenden Beispiel wird dieses Verhalten für eine geografische Breite/Länge in der Antarktis veranschaulicht. Auch wenn es keine Ergebnisse für den Reverse-Geocoding gibt, können wir den Pluscode in der Zusicherung drucken, wenn wir fulfillOnZeroResults=true festlegen.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(-75.290330, 38.653861);
      geocoder
        .geocode({
          'location': latlng,
          'fulfillOnZeroResults': true,
        })
        .then((response) => {
          console.log(response.plus_code);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }
  

Adressdeskriptoren

Adressbeschreibungen enthalten zusätzliche Informationen, die dazu beitragen, einen Ort anhand von Markierungen und Gebieten zu beschreiben. In der Demo zu Adressbeschreibungen können Sie sich die Funktion ansehen.

Adressbeschreibungen können mit dem Parameter extraComputations aktiviert werden. Fügen Sie extra_computations=ADDRESS_DESCRIPTORS in eine Geocoding-Anfrage, eine umgekehrte Geocoding-Anfrage oder eine Geocoding-Anfrage für Orte ein, um Adressbeschreibungen in Ihrer Antwort zu erhalten.

Beispiel für das Geocodieren von Orten

Die folgende Abfrage enthält die Adresse eines Ortes in Delhi.

function addressDescriptorPlaceIdLookup() {
  geocoder.geocode({ 
    'placeId': 'ChIJyxAX8Bj9DDkRgBfAnBYa66Q',
    'extraComputations': ['ADDRESS_DESCRIPTORS']
    }, function(results, status) {
    if (status == 'OK') {
      console.log(results[0].address_descriptor);
    } else {
      window.alert('Geocode was not successful for the following reason: ' + status);
    }
  });
}

Beispiel für die umgekehrte Geocodierung

Die folgende Abfrage enthält den Breiten-/Längengrad für einen Ort in Delhi.

    function addressDescriptorReverseGeocoding() {
      var latlng = new google.maps.LatLng(28.640964,77.235875);
      geocoder
        .geocode({
          'location': latlng,
          'extraComputations': ["ADDRESS_DESCRIPTORS"],
        })
        .then((response) => {
          console.log(response.address_descriptor);
        })
        .catch((error) => {
          window.alert(`Error`);
        });
    }
  

Beispiel für einen Adressdeskriptor

Ein Beispiel für address_descriptor sieht so aus:

  {
    "address_descriptor" : {
       "areas" : [
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Turkman Gate"
             },
             "place_id" : "ChIJ_7LLvyb9DDkRMKKxP9YyXgs"
          },
          {
             "containment" : "OUTSKIRTS",
             "display_name" : {
                "language_code" : "en",
                "text" : "Chandni Chowk"
             },
             "place_id" : "ChIJWcXciBr9DDkRUb4dCDykTwI"
          },
          {
             "containment" : "NEAR",
             "display_name" : {
                "language_code" : "en",
                "text" : "Katar Ganj"
             },
             "place_id" : "ChIJH3cWUyH9DDkRaw-9CjvcRvY"
          }
       ],
       "landmarks" : [
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delite Cinema"
             },
             "straight_line_distance_meters" : 29.9306755065918,
             "place_id" : "ChIJLfiYDCT9DDkROoEa7NdupUM",
             "travel_distance_meters" : 418.7794799804688,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "establishment", "movie_theater", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "YES Bank"
             },
             "straight_line_distance_meters" : 66.83731079101562,
             "place_id" : "ChIJFYHM3yb9DDkRRKGkZl2mpSQ",
             "travel_distance_meters" : 489.0340270996094,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "UCO Bank"
             },
             "straight_line_distance_meters" : 25.38849639892578,
             "place_id" : "ChIJ-c6_wCb9DDkRjIk1LeqRtGM",
             "travel_distance_meters" : 403.2246398925781,
             "spatial_relationship" : "ACROSS_THE_ROAD",
             "types" : [ "atm", "bank", "establishment", "finance", "point_of_interest" ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Delhi By Cycle Meeting Point"
             },
             "straight_line_distance_meters" : 44.02867126464844,
             "place_id" : "ChIJNxVfkSb9DDkRJD22l-eGFdM",
             "travel_distance_meters" : 97.41281890869141,
             "spatial_relationship" : "AROUND_THE_CORNER",
             "types" : [
                "establishment",
                "point_of_interest",
                "tourist_attraction",
                "travel_agency"
             ]
          },
          {
             "display_name" : {
                "language_code" : "en",
                "text" : "Axis Bank Branch"
             },
             "straight_line_distance_meters" : 102.3495178222656,
             "place_id" : "ChIJr3uaDCT9DDkR8roHTVSn1x4",
             "travel_distance_meters" : 330.8566284179688,
             "spatial_relationship" : "DOWN_THE_ROAD",
             "types" : [ "bank", "establishment", "finance", "point_of_interest" ]
          }
       ]
    }
  }

Jedes address_descriptor-Objekt enthält zwei Arrays: landmarks und areas. Das landmarks-Array enthält bis zu fünf Ergebnisse, die nach Relevanz sortiert sind. Dabei werden die Nähe zur angeforderten Koordinate, die Häufigkeit des Wahrzeichens und seine Sichtbarkeit berücksichtigt. Jedes Ergebnis für Markierungen enthält die folgenden Werte:

• place_id ist die Orts-ID des Ergebnisses für Sehenswürdigkeiten. Weitere Informationen finden Sie in der Übersicht zu Orts-IDs.
• display_name ist der Anzeigename des Wahrzeichens und enthält language_code und text.
• straight_line_distance_meters ist die Entfernung zwischen den Punkten in Metern zwischen der Eingabekoordinate und dem Ergebnis für Markierungen.
• travel_distance_meters ist die Entfernung in Metern, die über das Straßennetz zurückgelegt wurde (ohne Berücksichtigung von Straßeneinschränkungen) zwischen den Eingabekoordinaten und dem Ergebnis für Markierungen.
• spatial_relationship ist das geschätzte Verhältnis zwischen der Eingabekoordinate und dem Ergebnis für Markierungen:
• "NEAR" ist die Standardbeziehung, wenn keines der folgenden Kriterien zutrifft.
• "WITHIN", wenn sich die Eingabekoordinate innerhalb der Grenzen des Gebäudes befindet, das mit dem Wahrzeichen verknüpft ist.
• "BESIDE", wenn die Eingabekoordinate direkt neben dem Wahrzeichen oder dem Zugangspunkt des Wahrzeichens liegt.
• "ACROSS_THE_ROAD", wenn sich die Eingabekoordinate direkt gegenüber dem Wahrzeichen auf der anderen Seite der Route befindet.
• "DOWN_THE_ROAD", wenn sich die Eingabekoordinate auf derselben Route wie das Wahrzeichen befindet, aber nicht "BESIDES" oder "ACROSS_THE_ROAD".
• "AROUND_THE_CORNER", wenn sich die Eingabekoordinate entlang einer senkrechten Route wie das Wahrzeichen befindet (auf eine einzige Abbiegung beschränkt).
• "BEHIND", wenn sich die Eingabekoordinaten zwar in der Nähe des Wahrzeichens, aber weit vom Zugangspunkt entfernt befinden.
• types sind die Ortstypen der Sehenswürdigkeit.

Das areas-Objekt enthält bis zu drei Antworten und beschränkt sich auf Orte, die kleine Regionen darstellen, z. B. Stadtteile, Ortsteile und große Komplexe. Gebiete, die die angeforderte Koordinate enthalten, werden zuerst aufgeführt und von klein nach groß sortiert. Jedes areas-Ergebnis enthält die folgenden Werte:

• place_id ist die Orts-ID des Ergebnisses für „Bereiche“. Weitere Informationen finden Sie in der Übersicht zu Orts-IDs.
• display_name ist der Anzeigename des Gebiets und enthält language_code und text.
• containment ist das geschätzte Begrenzungsverhältnis zwischen der Eingabekoordinate und dem Ergebnis für die Bereiche:
• "NEAR" ist die Standardbeziehung, wenn keines der folgenden Kriterien zutrifft.
• "WITHIN", wenn sich die Eingabekoordinate nahe dem Zentrum des Gebiets befindet.
• "OUTSKIRTS", wenn sich die Eingabekoordinate nahe am Rand des Gebiets befindet.

Abdeckung des Adressdeskriptors

Diese Funktion ist nur in ausgewählten Ländern verfügbar.

Dies ist eine Vorabversion und wir würden uns über Feedback freuen. Bitte senden Sie uns eine E-Mail an address-descriptors-feedback@google.com.

Umgekehrte Geocodierung (Adresssuche)

Der Begriff Geocoding bezeichnet im Allgemeinen die Umwandlung einer Adresse in visuell lesbarer Form in einen Standort auf einer Karte. Der umgekehrte Prozess, also die Umwandlung eines Standortes auf einer Karte in eine Adresse in visuell lesbarer Form, wird als umgekehrte Geocodierung bezeichnet.

Geben Sie statt eines address-Elements in Textform ein kommagetrenntes Längen- und Breitengradpaar in den location-Parameter ein.

Im folgenden Beispiel wird ein Breiten-/Längengradwert geocodiert und die Karte um den entsprechenden Standort zentriert, an dem ein Infofenster mit der formatierten Adresse angezeigt wird.

function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.731, lng: -73.997 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodeLatLng(geocoder, map, infowindow);
    }
  );
}

function geocodeLatLng(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const input = (document.getElementById("latlng") as HTMLInputElement).value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.731, lng: -73.997 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodeLatLng(geocoder, map, infowindow);
  });
}

function geocodeLatLng(geocoder, map, infowindow) {
  const input = document.getElementById("latlng").value;
  const latlngStr = input.split(",", 2);
  const latlng = {
    lat: parseFloat(latlngStr[0]),
    lng: parseFloat(latlngStr[1]),
  };

  geocoder
    .geocode({ location: latlng })
    .then((response) => {
      if (response.results[0]) {
        map.setZoom(11);

        const marker = new google.maps.Marker({
          position: latlng,
          map: map,
        });

        infowindow.setContent(response.results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js

Im vorherigen Beispiel wurde das erste Ergebnis durch Auswählen von results[0] angezeigt. Bei der umgekehrten Geocodierung wird häufig mehr als ein Ergebnis zurückgegeben. Adressen nach Anwendung eines Geocodings bestehen nicht nur aus Postanschriften, sondern umfassen sämtliche geografischen Bezeichnungen für den Ort. Wenn Sie z. B. einen Punkt in Chicago geocodieren, kann er als Postanschrift, Stadt (Chicago), Bundesstaat (Illinois) oder Land (USA) gekennzeichnet sein. Alle diese Angaben gelten im Geocoder als Adressen. Bei der umgekehrten Geocodierung werden alle genannten Ergebnisse zurückgegeben.

Die umgekehrte Geocodierung gleicht Verwaltungseinheiten (Länder, Provinzen, Städte, Stadtteile), Adressen und Postleitzahlen ab.

Im folgenden Beispiel sehen Sie die Liste der Adressen, die voraussichtlich bei der oben angegebenen Anfrage zurückgegeben werden:

results[0].formatted_address: "277 Bedford Ave, Brooklyn, NY 11211, USA"
results[1].formatted_address: "Grand St/Bedford Av, Brooklyn, NY 11211, USA"
results[2].formatted_address: "Williamsburg, Brooklyn, NY, USA"
results[3].formatted_address: "Brooklyn, NY, USA"
results[4].formatted_address: "New York, NY, USA"
results[5].formatted_address: "Brooklyn, NY 11211, USA"
results[6].formatted_address: "Kings County, NY, USA"
results[7].formatted_address: "New York-Northern New Jersey-Long Island, NY-NJ-PA, USA"
results[8].formatted_address: "New York Metropolitan Area, USA"
results[9].formatted_address: "New York, USA"

Die Adressen werden absteigend nach dem Grad der Übereinstimmung sortiert. Normalerweise wird die am besten passende Adresse an erster Stelle angezeigt. Es werden verschiedene Arten von Adressen ausgegeben, von den genauen Adressen, d. h. Straßen, bis hin zu weniger genauen politischen Einheiten wie Stadtteilen, Städten, Landkreisen oder Bundesländern. Wenn Sie eine allgemeinere Adresse erhalten möchten, können Sie das Feld results[].types nutzen.

Hinweis: Die umgekehrte Geocodierung ist nicht ganz genau. Mit dem Geocoder wird versucht, den nächstgelegenen Ort mit einer Adresse zu finden, wobei eine gewisse Toleranz angewendet wird.

Adresse für eine Orts-ID abrufen

Geben Sie eine placeId an, um die Adresse für eine bestimmte Orts-ID zu ermitteln. Die Orts-ID ist eine eindeutige Kennung, die mit anderen Google APIs verwendet werden kann. Sie können z. B. die von der Roads API zurückgegebene placeId angeben, um die Adresse für einen bestimmten Punkt abzurufen. Weitere Informationen finden Sie in der Übersicht zur Orts-ID.

Wenn Sie eine placeId angeben, darf die Anfrage keines der folgenden Felder enthalten:

• address
• latLng
• location
• componentRestrictions

Im folgenden Beispiel wird eine Orts-ID weitergegeben, die zugehörige Adresse ermittelt und die Karte am entsprechenden Standort zentriert. Außerdem wird ein Infofenster mit der formatierten Adresse des jeweiligen Ortes angezeigt:

// Initialize the map.
function initMap(): void {
  const map = new google.maps.Map(
    document.getElementById("map") as HTMLElement,
    {
      zoom: 8,
      center: { lat: 40.72, lng: -73.96 },
    }
  );
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  (document.getElementById("submit") as HTMLElement).addEventListener(
    "click",
    () => {
      geocodePlaceId(geocoder, map, infowindow);
    }
  );
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(
  geocoder: google.maps.Geocoder,
  map: google.maps.Map,
  infowindow: google.maps.InfoWindow
) {
  const placeId = (document.getElementById("place-id") as HTMLInputElement)
    .value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

declare global {
  interface Window {
    initMap: () => void;
  }
}
window.initMap = initMap;
index.ts

// Initialize the map.
function initMap() {
  const map = new google.maps.Map(document.getElementById("map"), {
    zoom: 8,
    center: { lat: 40.72, lng: -73.96 },
  });
  const geocoder = new google.maps.Geocoder();
  const infowindow = new google.maps.InfoWindow();

  document.getElementById("submit").addEventListener("click", () => {
    geocodePlaceId(geocoder, map, infowindow);
  });
}

// This function is called when the user clicks the UI button requesting
// a geocode of a place ID.
function geocodePlaceId(geocoder, map, infowindow) {
  const placeId = document.getElementById("place-id").value;

  geocoder
    .geocode({ placeId: placeId })
    .then(({ results }) => {
      if (results[0]) {
        map.setZoom(11);
        map.setCenter(results[0].geometry.location);

        const marker = new google.maps.Marker({
          map,
          position: results[0].geometry.location,
        });

        infowindow.setContent(results[0].formatted_address);
        infowindow.open(map, marker);
      } else {
        window.alert("No results found");
      }
    })
    .catch((e) => window.alert("Geocoder failed due to: " + e));
}

window.initMap = initMap;
index.js