Flächenservice (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

  • Flächenservice
  • Ressourcen-Pfad
  • Authentifizierung
  • Parameter
  • Rückgabe
  • Beispiel
  • Fehler

Flächenservice

Übergeben Sie dem SmartMaps-Flächenservice eine beliebige Koordinate; wir ermitteln für Sie die zugehörigen administrativen Flächen oder Postleitzahlenbereiche, um sie in der Karte darzustellen.

Der Service ist aktuell in Deutschland, Österreich und der Schweiz nutzbar.

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/area

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/area?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/area?systemPartner=XXXX&securityID=XXXX

Parameter

Die Parameter werden im body, des POST-Request als JSON mitgeschickt.
{
    "type": "Feature",
    "crs": {
        "type": "name",
        "properties": {
            "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
        }
    },
    "properties": {},
    "searchparams": {
        "coordFormatOut": "GEODECIMAL_POINT",
        "levels": [
            1
        ],
        "providerId": "OSM"
    },
    "authentication": {
        "channel": ""
    },
    "geometry": {
        "type": "Point",
        "coordinates": [
            9.650074587837178,
            50.37910121895557
        ]
    }
}
Name Beschreibung Datentyp Standardwert
type Gibt an, um welchen Type es sich laut geoJSON handelt. string
crs.type Gibt den Typ von dem Koordinatenreferenzsystem an. string
crs.properties.name Gibt den Namen von dem Koordinatenreferenzsystem an. 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
searchparams.levels Das Array gibt an, welche Polygone zurückgegeben werden sollen. Folgende Werte können übergeben werden:
  • 0 - Land
  • 1 - Bundesland
  • 2 - Regierungsbezirk
  • 3 - Landkreis
  • 4 - PLZ
  • 5 - Gemeinde
  • 6 - Stadtteil
 Number
searchparams.providerId Gibt an, unter welchem Provider gesucht werden soll. Folgende Werte können übergeben werden:
  • OSM - OpenStreetMaps
 string
authentication.channel Beliebige Zeichenfolge, die protokolliert wird und dazu dient, den Aufruf später zu identifizieren. Sie kann frei gewählt werden. string
geometry.type Legt den übergebenen Typ fest, siehe geoJson string
geometry.coordinates Der Längen- und Breitengrad, der geografischen Koordinate. double[]

Rückgabe

Die Rückgabe ist ein geoJson.

{
    "type": "Feature",
    "crs": {
    "properties": {
        "exception": null
    },
    "features": [
        {
            "id": "DE0606631016________OSM",
            "properties": {
                "state": null,
                "description": "Kalbach",
                "city": "Kalbach",
                "country": null,
                "isoCountry": null,
                "district": null,
                "cityAddon": null,
                "cityPart": null,
                "houseNo": null,
                "street": null,
                "zip": null
            },
            "geometry": {
                "coordinates": [
                    [
                        [
                            9.61109,
                            50.4166
                        ],
                        [
                            9.61992,
                            50.41165
                        ],
                        [
                            9.61968,
                            50.40374
                        ],
                        ...
                    ]
                ],
                "type": "Polygon"
            },
            "bbox": [
                9.61109,
                50.35616,
                9.75973,
                50.4699
            ],
            "type": "Feature"
        }
    ],
    "bbox": [
        9.61109,
        50.35616,
        9.75973,
        50.4699
    ],
    "type": "FeatureCollection"
}
Name Beschreibung Datentyp
type Gibt an, um welchen Type es sich laut geoJSON handelt. string
crs.properties.exception Gibt die Fehlerbeschreibung an, falls ein Fehler aufgetaucht ist. ?string
features.properties.id Gibt die interne Id an, für den Provider. ?string
features.properties.state Gibt die Beschreibung des Staats an. ?string
features.properties.description Gibt die Beschreibung des Gebiets 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. Feature
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[]

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/area?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.