Adressen geocodieren

Entwickler im Europäischen Wirtschaftsraum (EWR)

Beim Geocoding wird eine Adresse in einen Standort auf einer Karte umgewandelt. Wenn Sie eine Adresse geocodieren, enthält die Antwort Folgendes:

  • Orts-ID des Standorts
  • Breiten- und Längengradkoordinaten des Standorts
  • Plus Code des Standorts
  • Erweiterte Adressdetails

Geocode-Anfrage

Eine Geocode-Anfrage ist eine HTTP-GET-Anfrage. Sie können die Adresse als eine unstrukturierte Zeichenfolge angeben:

https://geocode.googleapis.com/v4/geocode/address/ADDRESS_STRING

Oder als eine strukturierte Gruppe von Adresskomponenten, die durch Abfrageparameter dargestellt werden:

https://geocode.googleapis.com/v4/geocode/address?STRUCTURED_ADDRESS

Das strukturierte Format wird in der Regel verwendet, wenn Adresskomponenten verarbeitet werden, die in einem HTML-Formular erfasst wurden.

Übergeben Sie alle anderen Parameter als URL-Parameter oder, bei Parametern wie dem API-Schlüssel und der Feldmaske, in Headern als Teil der GET-Anfrage.

Unstrukturierte Adresszeichenfolge übergeben

Eine unstrukturierte Adresse ist eine Adresse, die als Zeichenfolge oder Plus Code formatiert ist. Beim Geocoding von Adressen werden keine Breiten- und Längengradkoordinaten oder andere unstrukturierte Zeichenfolgen aufgelöst, die keine Adresse oder keinen Plus Code darstellen. Anfragen mit solchen Zeichenfolgen werden nicht unterstützt und können zu Fehlerantworten oder nicht spezifiziertem Verhalten führen. Beispiele für nicht unterstützte Abfragen:

Abfragetyp Beispiel
Breiten- und Längengradkoordinaten Verwenden Sie stattd0}die umgekehrte Geocodierungessen. "37.422131,-122.084801"
Zu viele Konzepte oder Einschränkungen, z. B. die Namen mehrerer Orte, Straßen oder Städte in einer einzelnen Abfrage "Market Street San Francisco San Jose Airport"
Postadressenelemente, die nicht auf Google Maps dargestellt werden "C/O John Smith 123 Main Street"
"P.O. Box 13 San Francisco"
Namen von Unternehmen, Ketten oder Kategorien in Kombination mit Orten, an denen diese Entitäten nicht verfügbar sind "Tesco near Dallas, Texas"
Mehrdeutige Abfragen mit mehreren Interpretationen "Charger drop-off"
Historische Namen, die nicht mehr verwendet werden "Middlesex United Kingdom"
Nicht geografische Elemente oder Intents "How many boats are in Ventura Harbor?"
Inoffizielle oder Vanity-Namen "The Jenga"
"The Helter Skelter"

Im folgenden Beispiel wird die URL-codierte Adresszeichenfolge „1600 Amphitheatre Parkway, Mountain View, CA“ übergeben:

https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA?key=API_KEY

Das Zeichen „+“ in der URL wird in ein Leerzeichen umgewandelt.

Sie können die Anfrage auch mit einem curl-Befehl stellen:

curl -H "X-Goog-Api-Key: API_KEY" \
"https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA"

Adressen können viele Arten von Sonderzeichen enthalten. Beispiel: „/“ wie in „7/1 King St, Concord West“. URL-codieren Sie „/“ als %2F:

https://geocode.googleapis.com/v4/geocode/address/7%2F1+King+St,+Concord+West
?key=API_KEY

Ein weiteres häufiges Beispiel ist das Zeichen „#“ wie in „9500 W Bryn Mawr Ave #650, Rosemont“. URL-codieren Sie „#“ als %2FE:

https://geocode.googleapis.com/v4/geocode/address/9500+W+Bryn+Mawr+Ave+%23650,+Rosemont?key=API_KEY

Im nächsten Beispiel geben Sie eine unstrukturierte Adresszeichenfolge als Plus Code 849VCWC8+R4 an. URL-codieren Sie das Zeichen „+“ als %2B:

https://geocode.googleapis.com/v4/geocode/address/849VCWC8%2BR4?key=API_KEY

Strukturierte Adresse übergeben

Geben Sie eine strukturierte Adresse mit dem address Abfrageparameter vom Typ PostalAddress an. Mit dem Objekt PostalAddress können Sie einige oder alle Adresskomponenten in der Anfrage als einzelne Abfrageparameter angeben.

Wenn Sie beispielsweise nur die Postleitzahl der Adresse angeben möchten, verwenden Sie PostalAddress.postalCode:

https://geocode.googleapis.com/v4/geocode/address?address.postalCode=01062&key=API_KEY

Wenn Sie mehrere Adresskomponenten angeben möchten, z. B. für Adresskomponenten, die in einem HTML-Formular erfasst wurden, verwenden Sie mehrere Abfrageparameter:

https://geocode.googleapis.com/v4/geocode/address?address.addressLines=1600+Amphithreater+Pkwy&address.locality=Mountain+View&address.administrativeArea=CA&key=API_KEY

Anfrage mit OAuth stellen

Die Geocoding API v4 unterstützt OAuth 2.0 für die Authentifizierung. Wenn Sie OAuth mit der Geocoding API verwenden möchten, muss dem OAuth-Token der richtige Bereich zugewiesen sein. Die Geocoding API unterstützt die folgenden Bereiche für die Verwendung mit der Geocodierung:

  • https://www.googleapis.com/auth/maps-platform.geocode : Mit allen Methoden der Geocoding API verwenden.
  • https://www.googleapis.com/auth/maps-platform.geocode.address : Nur mit GeocodeAddress für die Geocodierung verwenden.

Außerdem können Sie den allgemeinen Bereich https://www.googleapis.com/auth/cloud-platform für alle Methoden der Geocoding API verwenden. Dieser Bereich ist während der Entwicklung nützlich, aber nicht in der Produktion, da er ein allgemeiner Bereich ist, der Zugriff auf alle Methoden ermöglicht.

Weitere Informationen und Beispiele finden Sie unter OAuth verwenden.

Geocode-Antwort

Beim Geocoding wird ein GeocodeAddressResponse Objekt zurückgegeben, das das results Array von GeocodeResult Objekten enthält. Jedes GeocodeResult-Objekt steht für einen einzelnen Ort.

Das vollständige JSON-Objekt hat das folgende Format:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "placeId": "ChIJF4Yf2Ry7j4AR__1AkytDyAE",
      "location": {
        "latitude": 37.422010799999995,
        "longitude": -122.08474779999999
      },
      "granularity": "ROOFTOP",
      "viewport": {
        "low": {
          "latitude": 37.420656719708511,
          "longitude": -122.08547523029148
        },
        "high": {
          "latitude": 37.4233546802915,
          "longitude": -122.0827772697085
        }
      },
      "formattedAddress": "1600 Amphitheatre Pkwy, Mountain View, CA 94043, USA",
      "postalAddress": {
        "regionCode": "US",
        "languageCode": "en",
        "postalCode": "94043",
        "administrativeArea": "CA",
        "locality": "Mountain View",
        "addressLines": [
          "1600 Amphitheatre Pkwy"
        ]
      },
      "addressComponents": [
        {
          "longText": "1600",
          "shortText": "1600",
          "types": [
            "street_number"
          ]
        },
        {
          "longText": "Amphitheatre Parkway",
          "shortText": "Amphitheatre Pkwy",
          "types": [
            "route"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "street_address"
      ],
      "plusCode": {
        "globalCode": "849VCWC8+R4",
        "compoundCode": "CWC8+R4 Mountain View, CA, USA"
      }
    }
  ]
}

Erforderliche Parameter

  • address : Die Adresse oder der Plus Code die bzw. den Sie geocodieren möchten. Hinweis: Beim Geocoding von Adressen werden keine Breiten- und Längengradkoordinaten oder andere unstrukturierte Zeichenfolgen aufgelöst, die keine Adresse oder keinen Plus Code darstellen. Weitere Informationen und Beispiele für nicht unterstützte Abfragen finden Sie unter Unstrukturierte Adresszeichenfolge übergeben. 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 Etagenummer sollten vermieden werden. Elemente der Adresse sollten durch Leerzeichen getrennt sein die als %20 URL-codiert sind. Übergeben Sie die Adresse „24 Sussex Drive Ottawa ON“ beispielsweise so: 
    24%20Sussex%20Drive%20Ottawa%20ON
     Formatieren Sie Plus Codes wie unten gezeigt. Pluszeichen werden als %2B URL-codiert und Leerzeichen als %20:
    • Ein Global Code besteht aus einem vierstelligen Code für das Gebiet und einem mindestens sechsstelligen lokalen Code. Codieren Sie „849VCWC8+R9“ beispielsweise als 849VCWC8%2BR9.
    • Ein Compound Code ist ein mindestens sechsstelliger lokaler Code mit einem expliziten Ort. Codieren Sie „CWC8+R9 Mountain View, CA, USA“ beispielsweise als CWC8%2BR9%20Mountain%20View%20CA%20USA.

Optionale Parameter

  • locationBias

    Gibt einen Bereich für die Suche als Viewport an. Dieser Standort dient als Gewichtung. Das bedeutet, dass Ergebnisse in der Nähe des angegebenen Standorts zurückgegeben werden können, einschließlich Ergebnissen in der Nähe, aber außerhalb des Bereichs.

    Geben Sie die Region als rechteckigen Darstellungsbereich an. Ein Rechteck ist ein Darstellungsbereich für Breiten- und Längengrade, der als zwei diagonal gegenüberliegende Tief- und Hochpunkte dargestellt wird. Der Tiefpunkt markiert die südwestliche Ecke des Rechtecks und der Hochpunkt die nordöstliche Ecke.

    Ein Darstellungsbereich gilt als geschlossene Region, d. h., er umfasst auch seine Grenze. Die Breitengradgrenzen müssen zwischen -90 und 90 Grad liegen und die Längengradgrenzen zwischen -180 und 180 Grad:

    • Wenn low = high ist, besteht der Darstellungsbereich aus diesem einzelnen Punkt.
    • Wenn low.longitude > high.longitude ist, wird der Längengradbereich umgekehrt (der Darstellungsbereich überschreitet die 180-Grad- Linie).
    • Wenn low.longitude = -180 Grad und high.longitude = 180 Grad ist, umfasst der Darstellungsbereich alle Längengrade.
    • Wenn low.longitude = 180 Grad und high.longitude = -180 Grad ist, ist der Längengradbereich leer.
    • Wenn low.latitude > high.latitude ist, ist der Breitengradbereich leer.

    Sowohl „low“ als auch „high“ müssen ausgefüllt sein und das dargestellte Rechteck darf nicht leer sein. Ein leerer Darstellungsbereich führt zu einem Fehler.

    Diese Abfragezeichenfolge definiert beispielsweise einen Darstellungsbereich, der New York City vollständig umschließt:

    ?locationBias.rectangle.low.latitude=40.477398&locationBias.rectangle.low.longitude=-74.259087&locationBias.rectangle.high.latitude=40.91618&locationBias.rectangle.high.longitude=-73.70018

  • languageCode

    Die Sprache, in der Ergebnisse zurückgegeben werden sollen.

    • Hier finden Sie eine Liste der unterstützten Sprachen. Die unterstützten Sprachen werden regelmäßig von Google aktualisiert . Diese Liste ist daher möglicherweise nicht vollständig.
    • Wenn languageCode nicht angegeben wird, verwendet die API standardmäßig en. Wenn Sie einen ungültigen Sprachcode angeben, gibt die API einen INVALID_ARGUMENT Fehler zurück.
    • Die API versucht, eine Adresse anzugeben, die sowohl für den Nutzer als auch für Einheimische lesbar ist. Dazu werden Adressen in der lokalen Sprache zurückgegeben, bei Bedarf in ein für den Nutzer lesbares Schriftsystem transliteriert und die bevorzugte Sprache berücksichtigt. Alle anderen Adressen werden in der bevorzugten Sprache zurückgegeben. Adresskomponenten werden alle in derselben Sprache zurückgegeben, die anhand der ersten Komponente ausgewählt wird.
    • Wenn ein Name in der bevorzugten Sprache nicht verfügbar ist, verwendet die API die nächstbeste Übereinstimmung.
    • Die bevorzugte Sprache hat einen geringen Einfluss auf die Ergebnisse, die von der API zurückgegeben werden, und auf die Reihenfolge, in der sie zurückgegeben werden. Der Geocoder interpretiert Abkürzungen je nach Sprache unterschiedlich, z. B. die Abkürzungen für Straßentypen oder Synonyme, die in einer Sprache gültig sein können, in einer anderen jedoch nicht.

  • regionCode

    Der Regionscode als zweistelliger CLDR-Code. Es gibt keinen Standardwert. Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch.

    Beim Geocoding einer Adresse, Geocodierung, kann dieser Parameter die Ergebnisse des Dienstes für die angegebene Region beeinflussen, aber nicht vollständig einschränken. Beim Geocoding eines Standorts oder eines Ortes (umgekehrte Geocodierung oder Geocoding von Orten}) kann dieser Parameter verwendet werden, um die Adresse zu formatieren. In allen Fällen kann dieser Parameter die Ergebnisse aufgrund geltenden Rechts beeinflussen.

  • FieldMask

    Erstellen Sie eine Feldmaske für die Antwort, um die Felder anzugeben, die in der Antwort zurückgegeben werden sollen. Übergeben Sie die Feldmaske für die Antwort an die Methode, indem Sie den URL-Parameter $fields oder fields, oder indem Sie den HTTP-Header X-Goog-FieldMask verwenden. Die folgende Anfrage gibt beispielsweise nur das Feld placeID der Antwort zurück.

    curl -X GET -H 'Content-Type: application/json' \
-H 'X-Goog-FieldMask: results.placeId' \
-H "X-Goog-Api-Key: API_KEY" \
https://geocode.googleapis.com/v4/geocode/address/1600+Amphitheatre+Parkway,+Mountain+View,+CA
    Die Antwort lautet: 
    {
  "results": [
    {
      "placeId": "ChIJiSSC8QK6j4AR98Thup8mqTc"
    }
  ]
}

    Weitere Informationen finden Sie unter Zurückzugebende Felder auswählen.

Standortgewichtung

Mit dem Parameter locationBias können Sie den Geocoding-Dienst so einrichten, dass Ergebnisse innerhalb eines bestimmten Darstellungsbereichs (ausgedrückt als Begrenzungsrahmen) bevorzugt werden. Der Parameter locationBias definiert die Breiten- und Längengradkoordinaten der südwestlichen und nordöstlichen Ecke dieses Begrenzungsrahmens.

Bei einer Geocode-Anfrage für die Adresse „Washington“ können beispielsweise Ergebnisse für Washington, D.C. und für den US-Bundesstaat Washington zurückgegeben werden:

https://geocode.googleapis.com/v4/geocode/address/Washington?key=API_KEY

Die Antwort hat folgendes Format:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "placeId": "ChIJW-T2Wt7Gt4kRKl2I1CJFUsI",
      "location": {
        "latitude": 38.9071923,
        "longitude": -77.0368707
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "bounds": {
        "low": {
          "latitude": 38.7916449,
          "longitude": -77.119759
        },
        "high": {
          "latitude": 38.9958641,
          "longitude": -76.909393
        }
      },
      "formattedAddress": "Washington, DC, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "Washington",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "placeId": "ChIJ-bDD5__lhVQRuvNfbGh4QpQ",
      "location": {
        "latitude": 47.7510741,
        "longitude": -120.7401386
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024945,
          "longitude": -116.91607109999998
        }
      },
      "bounds": {
        "low": {
          "latitude": 45.543541,
          "longitude": -124.84897389999999
        },
        "high": {
          "latitude": 49.0024442,
          "longitude": -116.91607109999998
        }
      },
      "formattedAddress": "Washington, USA",
      "addressComponents": [
        {
          "longText": "Washington",
          "shortText": "WA",
          "types": [
            "administrative_area_level_1",
            "political"
          ],
          "languageCode": "en"
        },
      ...
      ],
      "types": [
        "administrative_area_level_1",
        "political"
      ]
    }
  ]
}

Wenn Sie jedoch einen locationBias-Parameter hinzufügen, der einen Begrenzungsrahmen um den nordöstlichen Teil der USA definiert, wird bei der Geocodierung nur die Stadt Washington, D.C. zurückgegeben:

https://geocode.googleapis.com/v4/geocode/address/Washington?locationBias.rectangle.low.latitude=36.47&locationBias.rectangle.low.longitude=-84.72&locationBias.rectangle.high.latitude=43.39&locationBias.rectangle.high.longitude=-65.90&key=API_KEY

Regionsgewichtung

In einer Geocode-Anfrage können Sie den Geocoding-Dienst so einrichten, dass Ergebnisse zurückgegeben werden, die nach einer bestimmten Region gewichtet sind. Verwenden Sie dazu den Parameter regionCode. Dieser Parameter entspricht einem zweistelligen CLDR-Code, der die Regionsgewichtung angibt. Die meisten CLDR-Codes sind mit den ISO 3166-1-Codes identisch.

Es gibt keinen Standardwert für regionCode. Bei der Geocodierung von „Toledo“ werden beispielsweise Ergebnisse für die USA und für Spanien zurückgegeben:

https://geocode.googleapis.com/v4/geocode/address/Toledo?key=API_KEY

Antwort:

{
  "results": [
    {
      "place": "//places.googleapis.com/places/ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "placeId": "ChIJeU4e_C2HO4gRRcM6RZ_IPHw",
      "location": {
        "latitude": 41.652805199999996,
        "longitude": -83.5378674
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "bounds": {
        "low": {
          "latitude": 41.579513,
          "longitude": -83.6944089
        },
        "high": {
          "latitude": 41.733036,
          "longitude": -83.4493851
        }
      },
      "formattedAddress": "Toledo, OH, USA",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "locality",
            "political"
          ],
          "languageCode": "en"
        },
        ...
      ],
      "types": [
        "locality",
        "political"
      ]
    },
    {
      "place": "//places.googleapis.com/places/ChIJkwyrlqwLag0RiQIn2fdIshM",
      "placeId": "ChIJkwyrlqwLag0RiQIn2fdIshM",
      "location": {
        "latitude": 39.8628296,
        "longitude": -4.0273067
      },
      "granularity": "APPROXIMATE",
      "viewport": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "bounds": {
        "low": {
          "latitude": 39.8116682,
          "longitude": -4.179933
        },
        "high": {
          "latitude": 39.9251319,
          "longitude": -3.8148935
        }
      },
      "formattedAddress": "Toledo, España",
      "addressComponents": [
        {
          "longText": "Toledo",
          "shortText": "Toledo",
          "types": [
            "administrative_area_level_4",
            "political"
          ],
          "languageCode": "es"
        },
        ...
      ],
      "types": [
        "administrative_area_level_4",
        "political"
      ]
    },
    ...
  ]
}

Bei einer Geocode-Anfrage für „Toledo“ mit regionCode=es (Spanien) werden nur Ergebnisse aus Spanien zurückgegeben:

https://geocode.googleapis.com/v4/geocode/address/Toledo?regionCode=es&key=API_KEY