Geocoding API reference

The SmartMaps Geocoding API allows you to geocode addresses and convert between addresses and geographic coordinates. It provides a REST interface for easy integration into your applications.

Endpoints

Geocode

Converts an address or search string into a geographic coordinate.

URL: https://www.yellowmap.de/api_rst/v2/geojson/geocode

Method: POST

Request Body:

The request body is a JSON object with the following properties:

Property	Type	Description
type	string	Specifies the type according to GeoJSON.
properties	object	Not used.
geometry.type	string	Sets the type passed, see GeoJSON.
geometry.coordinates	number[]	The longitude and latitude of the coordinate to be geocoded.
crs.type	string	Specifies the type of the coordinate reference system.
crs.properties.name	string	Specifies the name of the coordinate reference system.
searchparams.geocodingType	string	Sets the geocoding mode. Must be "GEOCODE".
searchparams.coordFormatOut	string	Coordinate format of the output coordinate. Supported values: "SUPERKONFORM", "MERCATOR", "GEODECIMAL", "GEODECIMAL_POINT".
authentication.channel	string	Any desired string that is logged and used to identify the call later. It can be freely chosen.
location.country	string	The country of the address to be geocoded.
location.district	string	The district of the address to be geocoded.
location.zip	string	The postal code of the address to be geocoded.
location.city	string	The city of the address to be geocoded.
location.cityAddOn	string	The city addon of the address to be geocoded.
location.cityPart	string	The city part of the address to be geocoded.
location.street	string	The street of the address to be geocoded.
location.houseNo	string	The house number of the address to be geocoded.
location.singleSlot	string	The search string of any number of details of the geocoding address.

Response:

The response is a GeoJSON object with the following properties:

Property	Type	Description
properties.exception.errCode	string	Specifies the error code if an error occurred during geocoding.
properties.exception.publicReport	string	Specifies the error message if an error occurred during geocoding.
features.properties.description	string	Specifies the description of the location.
features.properties.city	string	Indicates the city.
features.properties.country	string	Indicates the country.
features.properties.isoCountry	string	Indicates the country code.
features.properties.district	string	Indicates the district.
features.properties.cityAddon	string	Indicates the city addon.
features.properties.cityPart	string	Indicates the city part.
features.properties.houseNo	string	Indicates the house number.
features.properties.street	string	Indicates the street.
features.properties.zip	string	Indicates the postal code.
features.geometry	Geometry	Specifies the found object feature, see GeoJSON.
features.bbox	number[]	Specifies a rectangle in which the feature is located.
features.type	string	Indicates the type according to GeoJSON.
bbox	number[]	Specifies a rectangle in which all returned features are located.
type	string	Indicates the type according to GeoJSON.

Reverse Geocode

Converts a geographic coordinate into an address.

URL: https://www.yellowmap.de/api_rst/v2/geojson/geocode

Method: POST

Request Body:

The request body is a JSON object with the following properties:

Property	Type	Description
type	string	Specifies the type according to GeoJSON.
properties	object	Not used.
geometry.type	string	Sets the type passed, see GeoJSON.
geometry.coordinates	number[]	The longitude and latitude of the coordinate to be reverse geocoded.
location	object	Empty object.
crs.type	string	Specifies the type of the coordinate reference system.
crs.properties.name	string	Specifies the name of the coordinate reference system.
searchparams.geocodingType	string	Sets the geocoding mode. Must be "REVERSE_GEOCODE".
searchparams.coordFormatOut	string	Coordinate format of the output coordinate. Supported values: "SUPERKONFORM", "MERCATOR", "GEODECIMAL", "GEODECIMAL_POINT".
authentication.channel	string	Any desired string that is logged and used to identify the call later. It can be freely chosen.

Response:

The response is the same as the Geocode endpoint.

Authentication

To use the SmartMaps Geocoding API, you need an API key for authentication. The API key is passed as a URL parameter named apiKey.

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

Error Handling

The API may return the following HTTP status codes:

• 400 Bad Request: The request was made incorrectly, e.g., due to a syntax error in the JSON.
• 412 Precondition Failed: The API key was not provided.

Example

Here's an example request for geocoding an address:

curl --location --request POST 'https://www.yellowmap.de/api_rst/v2/geojson/geocode?apiKey=YOUR_API_KEY' \
--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"
  },
  "authentication": {
    "channel": "Test123"
  },
  "location": {
    "country": "DE",
    "district": "",
    "zip": "76131",
    "city": "Karlsruhe",
    "cityAddOn": "",
    "cityPart": "",
    "street": "CAS-Weg",
    "houseNo": "",
    "singleSlot": ""
  }
}'