Backend-Service

The backend services are independent services. This is an enterprise function of the SmartMaps. The functionality is not available in SmartMaps FREE. For the activation of a service and further questions we are at your disposal in our support area .

Navigation

Areaservice

Hand over any coordinate into the area service; we will determine the corresponding administrative areas or postal code areas for you in order to display them on the map.

The service is currently available in Germany, Austria and Switzerland.

Resource Path

The functionality is provided via a classic REST interface, which can be accessed via the following link:

POST https://www.yellowmap.de/api_rst/v2/geojson/area

Authentication

To use the interface, you need a partner name and an access key. You get both from YellowMap. For authentication, the partner name and the security key are each passed as URL parameters. The values are always to be transmitted URL-encoded.

Authentication via API key

Parameter	Description
`apiKey`	API key – received after registration.

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

Authentication via partner name and access key

Parameter	Description
`systemPartner`	Partner name – given from YellowMap.
`securityId`	Security key – given from YellowMap.

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

Parameter

The parameters are included in the body, of the POST request as JSON.

{
    "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	Description	Data type
`type`	Specifies what type it is according to geoJSON.	`string`
`crs.type`	Specifies the type of the coordinate reference system.	`string`
`crs.properties.name`	Specifies the name of the coordinate reference system.	`string`
`searchparams.coordFormatOut`	Coordinate format of the coordinate for geocode the address. One of the values from the list: `SUPERKONFORM` - Superkonform (Data format of the company PTV) `MERCATOR` - Mercator, the default coordinate format `GEODECIMAL` - Geodecimal multiplied by 100.000 `GEODECIMAL_POINT` - Geodecimal as float value (not multiplied by 100,000)	`string`
`searchparams.levels`	The array specifies which polygons are to be returned. The following values can be passed: `0` - Country `1` - State `2` - Government district `3` - County `4` - Postal Code `5` - Community `6` - City District	`Number`
`searchparams.providerId`	Specifies under which provider to search. The following values can be passed: `OSM` - OpenStreetMaps	`string`
`authentication.channel`	Any desired string that is logged and used to identify the call later. It can be freely chosen.	`string`
`geometry.type`	Specifies the passed type, see geoJson.	`string`
`geometry.coordinates`	The longitude and latitude, of the geographical coordinate.	`double[]`

Return

The return is a 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"
}

Example

Note that in the example {{system_Partner}} and {{security_id}} must be set.

Name	Description	Data type
`type`	Specifies what type it is according to geoJSON.	`string`
`crs.properties.exception`	Specifies the error description if an error occurred.	`?string`
`features.properties.id`	Specifies the internal Id, for the provider.	`?string`
`features.properties.state`	Specifies the state.	`?string`
`features.properties.description`	Specifies the description of the returned area.	`?string`
`features.properties.city`	Specifies the city.	`?string`
`features.properties.country`	Specifies the country.	`?string`
`features.properties.isoCountry`	Specifies the country code.	`?string`
`features.properties.district`	Specifies the district.	`?string`
`features.properties.cityAddon`	Specifies the city addon.	`?string`
`features.properties.cityPart`	Specifies the city part.	`?string`
`features.properties.houseNo`	Specifies the housenumber.	`?string`
`features.properties.street`	Specifies the street.	`?string`
`features.properties.zip`	Specifies the postal code.	`?string`
`features.geometry`	Specifies the found object as a feature, see geoJSON.	`Feature`
`features.bbox`	Specifies a rectangle in which the feature is located.	`double[]`
`features.type`	Specifies what type it is according to geoJSON.	`?string`
`bbox`	Specifies a rectangle in which all returned features are located.	`double[]`

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": ""
    }
}'

Error

HTTP-Statuscode	Description
400	BAD REQUEST, the request was made incorrectly.
412	PRECONDITION FAILED, the token was not handed over.