Geocodierung (POST)

  Backend-Service

Die Backend-Services sind eigenständige Services. Hierbei handelt es sich um eine Enterprise-Funktion der SmartMaps. Die Funktionalität ist in SmartMaps FREE nicht verfügbar. Für die Freischaltung eines Dienstes und weiteren Fragen stehen wir Ihnen gerne in unserem Supportbereich zur Verfügung.


Navigation

Geocode

Sie können mithilfe der SmartMaps-API sowohl beliebige Adressen geokodieren, als auch einer Koordinate eine Adresse zuordnen.

Ressourcen-Pfad

Bereitgestellt wird die Funktionalität über eine klassische REST-Schnittstelle, die über den folgenden Link aufgerufen werden kann:
POST https://www.yellowmap.de/api_rst/v2/geojson/geocode

Authentifizierung

Um die Schnittstelle verwenden zu können, benötigen Sie einen API-Key oder Ihren Partnernamen und den dazugehörigen Zugriffsschlüssel. Letztere erhalten Sie von YellowMap. Zur Authentifizierung werden die jeweiligen Zugangsdaten als URL-Parameter übergeben. Die Werte sind stets URL-enkodiert zu übermitteln.

Authentifizierung mittels API-Key

Parameter Bedeutung
apiKey API-Key – erhalten Sie nach Registrierung.

POST https://www.yellowmap.de/api_rst/v2/geojson/geocode?apiKey=XXXX

Authentifizierung mittels Partnername und Sicherheitsschlüssel

Parameter Bedeutung
systemPartner Partnername – gibt YellowMap vor.
securityId Zugriffsschlüssel – gibt YellowMap vor.

POST https://www.yellowmap.de/api_rst/v2/geojson/geocode?systemPartner=XXXX&securityID=XXXX

Parameter

Die Parameter werden im body, des POST-Request als JSON mitgeschickt.

Geocode (Adresse / Suchstring zu geographischer Koordinate)

Sie können den Typ "geocodingType": "GEOCODE" verwenden, um eine geografische Koordinate in Form eines location-Objekts (Adresse) oder einen Suchstring zu geokodieren.

{
    "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": {
        "country": "DE",
        "district": "",
        "zip": "76131",
        "city": "Karlsruhe",
        "cityAddOn": "",
        "cityPart": "",
        "street": "CAS-Weg",
        "houseNo": "",
        "singleSlot": ""
    }
}

Reverse Geocode (Geographische Koordinate zu Adresse)

Sie können den Typ "geocodingType": "REVERSE_GEOCODE" verwenden, um eine Adresse in Form einer geografischen Koordinate zu geokodieren.

{
    "type": "Feature",
    "properties": {},
    "geometry": {
        "type": "Point",
        "coordinates": [
            8.439451304332795,
            49.021658248904146
        ]
    },
    "location": {},
    "crs": {
        "type": "name",
        "properties": {
            "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
        }
    },
    "searchparams": {
        "geocodingType": "REVERSE_GEOCODE",
        "coordFormatOut": "GEODECIMAL_POINT"
    },
    "authentication": {
        "channel": ""
    }
}

Parameter

Name Beschreibung Datentyp Standardwert
type Gibt an, um welchen Type es sich laut geoJSON handelt. string
properties Wird nicht genutzt. dictionary
geometry.type Legt den übergebenen Typ fest, siehe geoJson string
geometry.coordinates Der Längen- und Breitengrad, der zu geokodierenden Koordinate. double[]
crs.type Gibt den Typ von dem Koordinatenreferenzsystem an. string
crs.properties.name Gibt den Namen von dem Koordinatenreferenzsystem an. string
searchparams.geocodingType Legt den Geokodierungsmodus fest. Einer der Werte aus der Liste:
  • GEOCODE - Ermöglicht es, eine Adresse oder einen Suchstring in eine geographische Koordinate umzuwandeln.
  • REVERSE_GEOCODE - Ermöglicht es, eine geographische Koordinate zu einer Adresse umzuwandeln.
 string
searchparams.coordFormatOut Koordinatenformat der Koordinate, für die eine Adresse ermittelt werden soll. Einer der Werte aus der Liste:
  • SUPERKONFORM - Superkonform (Datenformat der Firma PTV)
  • MERCATOR - Mercator, das Standard-Koordinatenformat
  • GEODECIMAL - Geodezimal multipliziert mit 100.000
  • GEODECIMAL_POINT - Geodezimal als Float-Wert (also nicht mit 100.000 multipliziert)
 string
authentication.channel Beliebige Zeichenfolge, die protokolliert wird und dazu dient, den Aufruf später zu identifizieren. Sie kann frei gewählt werden. string
location.country Das Land der zu geokodierenden Adresse. ?string
location.district Das Bundesland der zu geokodierenden Adresse. ?string
location.zip Die Postleitzahl der zu geokodierenden Adresse. ?string
location.city Die Stadt der zu geokodierenden Adresse. ?string
location.cityAddOn Die Verwaltungsregion der zu geokodierenden Adresse. ?string
location.cityPart Der Stadtteil der zu geokodierenden Adresse. ?string
location.street Die Straße der zu geokodierenden Adresse. ?string
location.houseNo Die Hausnummer der zu geokodierenden Adresse. ?string
location.singleSlot Der Suchstring aus beliebiger Anzahl von Angaben zu der geokodierenden Adresse. ?string

Rückgabe

Die Rückgabe ist ein geoJson.

{
    "properties": {
        "exception": {
            "errCode": "",
            "publicReport": ""
        }
    },
    "features": [
        {
            "properties": {
                "description": null,
                "city": "Karlsruhe",
                "country": "D",
                "isoCountry": "DE",
                "district": "Baden-Württemberg",
                "cityAddon": null,
                "cityPart": "Rintheim",
                "houseNo": null,
                "street": "CAS-Weg",
                "zip": "76131"
            },
            "geometry": {
                "coordinates": [
                    8.43942,
                    49.0215
                ],
                "type": "Point"
            },
            "bbox": [
                8.43942,
                49.0215,
                8.43942,
                49.0215
            ],
            "type": "Feature"
        }
    ],
    "bbox": [
        8.43942,
        49.0215,
        8.43942,
        49.0215
    ],
    "type": "FeatureCollection"
}

Eigenschaftsnamen

Name Beschreibung Datentyp
properties.exception.errCode Gibt den Error Code an, falls beim Geocodieren ein Fehler aufgetreten ist. string
properties.exception.publicReport Gibt die Error Nachricht an, falls beim Geocodieren ein Fehler aufgetreten ist. string
features.properties.description Gibt die Beschreibung des Orts an. ?string
features.properties.city Gibt die Stadt an. ?string
features.properties.country Gibt das Land an. ?string
features.properties.isoCountry Gibt den Ländercode an. ?string
features.properties.district Gibt das Bundesland an. ?string
features.properties.cityAddon Gibt die Verwaltungsregion an. ?string
features.properties.cityPart Gibt den Stadteil an. ?string
features.properties.houseNo Gibt die Hausnummer an. ?string
features.properties.street Gibt die Straße an. ?string
features.properties.zip Gibt die Postleitzahl an. ?string
features.geometry Gibt das gefundene Objekt als feature an, siehe geoJSON. Geometry
features.bbox Gibt ein Rechteck an, in dem sich das Feature befindet. double[]
features.type Gibt an, um welchen Type es sich laut geoJSON handelt. string
bbox Gibt ein Rechteck an, in dem sich alle zurückgegebenen Features befinden. double[]
type Gibt an, um welchen Type es sich laut geoJSON handelt. string

Beispiel

Beachten Sie, dass in dem Beispiel {{system_Partner}} und {{security_id}} gesetzt werden muss.
curl --location --request POST 'https://www.yellowmap.de/api_rst/v2/geojson/geocode?systemPartner={{system_Partner}}&securityID={{security_id}}' \
--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",
        "isoLocale": "de-DE"
    },
    "authentication": {
        "channel": "Test123"
    },
    "location": {
        "country": "DE",
        "district": "",
        "zip": "76131",
        "city": "Karlsruhe",
        "cityAddOn": "",
        "cityPart": "",
        "street": "CAS-Weg",
        "houseNo": "",
        "singleSlot": ""
    }
}'

Fehler

HTTP-Statuscode Beschreibung
400
BAD REQUEST, die Anfrage wurde falsch gestellt.
412
PRECONDITION FAILED, der Token wurde nicht übergeben.