Areaservice (POST)

  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 Default value
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.