Geocode (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

Geocode

You can geocode any address using the SmartMaps-API, as well as assign an address to a coordinate.

Ressource  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/geocode

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

Parameter

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

Geocode (address / search string to geographic coordinate)

You can use the type "geocodingType": "GEOCODE" to geocode a geographic coordinate in the form of a location object (address) or a search string.

{
    "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 (geographic coordinate to address)

You can use the type "geocodingType": "REVERSE_GEOCODE" to geocode an address in the form of a geographic coordinate.

{
    "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 Description Data type Default value
type Specifies what type it is according to geoJSON. string
properties Not used. dictionary
geometry.type Sets the type passed, see geoJson. string
geometry.coordinates The longitude and latitude, of the coordinate to be geocoded. double[]
crs.type Specifies the type of the coordinate reference system. string
crs.properties.name Specifies the name of the coordinate reference system. string
searchparams.geocodingType Sets the geocoding mode. One of the values from the list:
  • GEOCODE - Allows to convert an address or a search string into a geographic coordinate.
  • REVERSE_GEOCODE - Allows to convert a geographic coordinate to an address.
 string
searchparams.coordFormatOut Coordinate format of the coordinate for which an address is to be determined. One of the values from the list:
  • SUPERKONFORM - Superkonform (PTV Company Data Format)
  • MERCATOR - Mercator, the default coordinate format
  • GEODECIMAL - Geodecimal multiplied by 100,000
  • GEODECIMAL_POINT - Geodecimal as float value (not multiplied by 100,000)
 string
authentication.channel Any desire string that is logged and used to identify the call later. It can be freely chosen. string
location.country The country of the address to be geocoded. ?string
location.district The district of the address to be geocoded. ?string
location.zip The postal code of the address to be geocoded. ?string
location.city The city of the address to be geocoded. ?string
location.cityAddOn The city addon of the address to be geocoded. ?string
location.cityPart The city part of the address to be geocoded. ?string
location.street The street of the address to be geocoded. ?string
location.houseNo The housenumber of the address to be geocoded. ?string
location.singleSlot The search string of any number of details of the geocoding address. ?string

Return

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

Property names

Name Description Data type
properties.exception.errCode Specifies the error code if an error occurred during geocoding. string
properties.exception.publicReport Specifies the error message if an error occurred during geocoding. string
features.properties.description Specifies the description of the location. ?string
features.properties.city Indicates the city. ?string
features.properties.country Indicates the country. ?string
features.properties.isoCountry Indicates the country code. ?string
features.properties.district Indicates the district. ?string
features.properties.cityAddon Indicates the city addon. ?string
features.properties.cityPart Indicates the citypart. ?string
features.properties.houseNo Indicates the housenumber. ?string
features.properties.street Indicates the street. ?string
features.properties.zip Indicates the postal code. ?string
features.geometry Specifies the found object feature, see geoJSON. Geometry
features.bbox Specifies a rectangle in which the feature is located. double[]
features.type Indicates what type it is according to geoJSON. string
bbox Specifies a rectangle in which all returned features are located. double[]
type Indicates what type it is according to geoJSON. string

Example

Note that in the example {{system_Partner}} and {{security_id}} must be set.
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": ""
    }
}'

Error

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