Geocoding API-Referenz

Die SmartMaps Geocoding API ermöglicht das Geocoding von Adressen und die Umwandlung zwischen Adressen und geografischen Koordinaten. Sie stellt eine REST-Schnittstelle für die einfache Integration in Ihre Anwendungen bereit.

Koordinatenreihenfolge

Diese REST API verwendet die GeoJSON-Koordinatenreihenfolge: [longitude, latitude]. Beachten Sie, dass die Kartenmethoden von SmartMaps GL JS { lat, lng }-Objekte erwarten (Breitengrad zuerst). Eine Verwechslung der beiden ist eine häufige Ursache dafür, dass Punkte an der falschen Stelle landen.

Endpunkte

Geocode

Wandelt eine Adresse oder Suchzeichenfolge in eine geografische Koordinate um.

URL: https://www.yellowmap.de/api_rst/v2/geojson/geocode

Methode: POST

Anfragetext:

Der Anfragetext ist ein JSON-Objekt mit den folgenden Eigenschaften:

Property	Type	Description
`type`	string	Gibt den Typ gemäß GeoJSON an.
`properties`	object	Wird nicht verwendet.
`geometry.type`	string	Legt den übergebenen Typ fest, siehe GeoJSON.
`geometry.coordinates`	number[]	Der Längen- und Breitengrad der zu geocodierenden Koordinate.
`crs.type`	string	Gibt den Typ des Koordinatenreferenzsystems an.
`crs.properties.name`	string	Gibt den Namen des Koordinatenreferenzsystems an.
`searchparams.geocodingType`	string	Legt den Geocoding-Modus fest. Muss `"GEOCODE"` sein.
`searchparams.coordFormatOut`	string	Koordinatenformat der Ausgabekoordinate. Unterstützte Werte: `"SUPERKONFORM"`, `"MERCATOR"`, `"GEODECIMAL"`, `"GEODECIMAL_POINT"`.
`authentication.channel`	string	Eine beliebige Zeichenfolge, die protokolliert und später zur Identifizierung des Aufrufs verwendet wird. Sie kann frei gewählt werden.
`location.country`	string	Das Land der zu geocodierenden Adresse.
`location.district`	string	Der Bezirk der zu geocodierenden Adresse.
`location.zip`	string	Die Postleitzahl der zu geocodierenden Adresse.
`location.city`	string	Die Stadt der zu geocodierenden Adresse.
`location.cityAddOn`	string	Der Stadtzusatz der zu geocodierenden Adresse.
`location.cityPart`	string	Der Stadtteil der zu geocodierenden Adresse.
`location.street`	string	Die Straße der zu geocodierenden Adresse.
`location.houseNo`	string	Die Hausnummer der zu geocodierenden Adresse.
`location.singleSlot`	string	Die Suchzeichenfolge für eine beliebige Anzahl von Details der zu geocodierenden Adresse.

Antwort:

Die Antwort ist ein GeoJSON-Objekt mit den folgenden Eigenschaften:

Property	Type	Description
`properties.exception.errCode`	string	Gibt den Fehlercode an, falls beim Geocoding ein Fehler aufgetreten ist.
`properties.exception.publicReport`	string	Gibt die Fehlermeldung an, falls beim Geocoding ein Fehler aufgetreten ist.
`features.properties.description`	string	Gibt die Beschreibung des Standorts an.
`features.properties.city`	string	Gibt die Stadt an.
`features.properties.country`	string	Gibt das Land an.
`features.properties.isoCountry`	string	Gibt den Ländercode an.
`features.properties.district`	string	Gibt den Bezirk an.
`features.properties.cityAddon`	string	Gibt den Stadtzusatz an.
`features.properties.cityPart`	string	Gibt den Stadtteil an.
`features.properties.houseNo`	string	Gibt die Hausnummer an.
`features.properties.street`	string	Gibt die Straße an.
`features.properties.zip`	string	Gibt die Postleitzahl an.
`features.geometry`	Geometry	Gibt das gefundene Objekt-Feature an, siehe GeoJSON.
`features.bbox`	number[]	Gibt ein Rechteck an, in dem sich das Feature befindet.
`features.type`	string	Gibt den Typ gemäß GeoJSON an.
`bbox`	number[]	Gibt ein Rechteck an, in dem sich alle zurückgegebenen Features befinden.
`type`	string	Gibt den Typ gemäß GeoJSON an.

Reverse Geocode

Wandelt eine geografische Koordinate in eine Adresse um.

URL: https://www.yellowmap.de/api_rst/v2/geojson/geocode

Methode: POST

Anfragetext:

Der Anfragetext ist ein JSON-Objekt mit den folgenden Eigenschaften:

Property	Type	Description
`type`	string	Gibt den Typ gemäß GeoJSON an.
`properties`	object	Wird nicht verwendet.
`geometry.type`	string	Legt den übergebenen Typ fest, siehe GeoJSON.
`geometry.coordinates`	number[]	Der Längen- und Breitengrad der per Reverse-Geocoding aufzulösenden Koordinate.
`location`	object	Leeres Objekt.
`crs.type`	string	Gibt den Typ des Koordinatenreferenzsystems an.
`crs.properties.name`	string	Gibt den Namen des Koordinatenreferenzsystems an.
`searchparams.geocodingType`	string	Legt den Geocoding-Modus fest. Muss `"REVERSE_GEOCODE"` sein.
`searchparams.coordFormatOut`	string	Koordinatenformat der Ausgabekoordinate. Unterstützte Werte: `"SUPERKONFORM"`, `"MERCATOR"`, `"GEODECIMAL"`, `"GEODECIMAL_POINT"`.
`authentication.channel`	string	Eine beliebige Zeichenfolge, die protokolliert und später zur Identifizierung des Aufrufs verwendet wird. Sie kann frei gewählt werden.

Antwort:

Die Antwort entspricht der des Geocode-Endpunkts.

Authentifizierung

Um die SmartMaps Geocoding API zu nutzen, benötigen Sie einen API-Key zur Authentifizierung. Der API-Key wird als URL-Parameter mit dem Namen apiKey übergeben.

https://www.yellowmap.de/api_rst/v2/geojson/geocode?apiKey=[INSERT API-KEY]

Fehlerbehandlung

Die API kann die folgenden HTTP-Statuscodes zurückgeben:

400 Bad Request: Die Anfrage wurde fehlerhaft gestellt, z. B. aufgrund eines Syntaxfehlers im JSON.
412 Precondition Failed: Der API-Key wurde nicht angegeben.

Beispiel

Hier ist eine Beispielanfrage zum Geocoding einer Adresse:

curl --location --request POST 'https://www.yellowmap.de/api_rst/v2/geojson/geocode?apiKey=[INSERT API-KEY]' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "Feature",
  "properties": {},
  "geometry": {
    "type": "Point",
    "coordinates": [0, 0]
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "searchparams": {
    "geocodingType": "GEOCODE",
    "coordFormatOut": "GEODECIMAL_POINT"
  },
  "authentication": {
    "channel": "Test123"
  },
  "location": {
    "isoCountry": "DE",
    "district": "",
    "zip": "76131",
    "city": "Karlsruhe",
    "cityAddOn": "",
    "cityPart": "",
    "street": "CAS-Weg",
    "houseNo": "",
    "singleSlot": ""
  }
}'