Routing API reference

The SmartMaps Routing API provides functionality for calculating routes, distance matrices, optimized trips, and isochrones. It allows you to find the best paths between locations, calculate travel times and distances, optimize multi-stop trips, and determine reachable areas based on time or distance.

Endpoints

Route

Calculates a route between two or more coordinates with optional intermediate points.

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

Method: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "ROUTE",
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.362124135917012, 49.01062717784205]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.437334508302376, 49.004997061308316]
      },
      "properties": {}
    },
    {
      "type": "Feature", 
      "geometry": {
        "type": "Point",
        "coordinates": [8.381356011960742, 48.99103162515999]
      },
      "properties": {}
    }
  ]
}

Parameters:

Parameter	Type	Description
`type`	string	Specifies the GeoJSON type.
`routingparams.type`	string	Must be set to `"ROUTE"`.
`routingparams.isoLocale`	string	Sets the language of the route instructions.
`routingparams.coordFormatOut`	string	Coordinate format of the output coordinate. Supported values: `"SUPERKONFORM"`, `"MERCATOR"`, `"GEODECIMAL"`, `"GEODECIMAL_POINT"`.
`routingparams.speedProfile`	string	Speed profile for the route calculation. Supported values: `"FAST"`, `"SLOW"`, `"BICYCLE"`, `"PEDESTRIAN"`.
`routingparams.routingTimeMode`	string	Defines how the time is calculated. Supported values: `"ARRIVAL"`, `"DEPARTURE"`.
`authentication.channel`	string	Any desired string for logging and identifying the request.
`crs.type`	string	Specifies the type of the coordinate reference system.
`crs.properties.name`	string	Specifies the name of the coordinate reference system.
`features`	array	Array of GeoJSON features representing the route points. The first point is the starting point, followed by intermediate points, and the last point is the destination.

Response:

The response is a GeoJSON FeatureCollection containing the calculated route and directions.

Matrix

Calculates the distance and travel time between multiple coordinates and one coordinate.

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

Method: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "MATRIX",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.331952086718967, 49.01603149080641]
      },
      "properties": {
        "type": "StartPoint"
      }
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [8.391008912120817, 49.02121007355168],
          [8.38688866848814, 48.996438064932285],
          [8.364227328508337, 49.00139345263399]
        ]
      },
      "properties": {}
    }
  ]
}

Parameters:

Similar to the Route endpoint, with the following differences:

Parameter	Type	Description
`routingparams.type`	string	Must be set to `"MATRIX"`.
`features`	object	Specifies the starting point.
`features[1]`	object	Specifies the end points as a `MultiPoint` geometry.

Response:

The response is a GeoJSON FeatureCollection containing the distance and travel time between the starting point and each end point.

Trip

Calculates the optimal approach route between a start destination and multiple destinations.

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

Method: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "TRIP",
    "routingRoundTrip": false,
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "MultiPoint",
        "coordinates": [
          [8.378608601097369, 49.00882560981356],
          [8.45553610527237, 49.00139345263399]
        ]
      },
      "properties": {}
    }
  ]
}

Parameters:

Similar to the Route endpoint, with the following differences:

Parameter	Type	Description
`routingparams.type`	string	Must be set to `"TRIP"`.
`routingparams.routingRoundTrip`	boolean	When `true`, the starting point is also the final destination.
`features`	array	Passing more than one point as a `MultiPoint` geometry. The first point is the starting point, and all other points are intermediate points.

Response:

The response is a GeoJSON FeatureCollection containing the optimized route between the starting point and the intermediate points.

Isochrone

Calculates the area covered by a given travel time or travel distance.

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

Method: POST

Request Body:

{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "ISOCHRONE",
    "timeInMinutes": 40,
    "distanceInMeters": null,
    "isochroneGrid": "100",
    "speedProfile": "FAST",
    "coordFormatOut": "GEODECIMAL_POINT",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": "TEST123"
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.34566116333008, 48.9786396543091]
      },
      "properties": {}
    }
  ]
}

Parameters:

Similar to the Route endpoint, with the following differences:

Parameter	Type	Description
`routingparams.type`	string	Must be set to `"ISOCHRONE"`.
`routingparams.timeInMinutes`	number	Time in minutes for the isochrone calculation. Can take values from >0 to 60. Either `timeInMinutes` or `distanceInMeters` can be passed.
`routingparams.distanceInMeters`	number	Distance in meters for the isochrone calculation. Either `timeInMinutes` or `distanceInMeters` can be passed.
`routingparams.isochroneGrid`	string	Defines the fineness of the polygon that will be calculated. The higher the value, the finer the polygon. Can take values from 35 to 150.
`features`	array	A single point that serves as the starting point for the isochrone calculation.

Response:

The response is a GeoJSON FeatureCollection containing the isochrone polygon and the origin point.

Authentication

To use the SmartMaps Routing 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/route?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 calculating a route:

curl --location --request POST 'https://www.yellowmap.de/api_rst/v2/geojson/route?apiKey=YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "FeatureCollection",
  "routingparams": {
    "type": "ROUTE",
    "isoLocale": "de-DE",
    "coordFormatOut": "GEODECIMAL_POINT",
    "speedProfile": "FAST",
    "routingTimeMode": "ARRIVAL"
  },
  "authentication": {
    "channel": ""
  },
  "crs": {
    "type": "name",
    "properties": {
      "name": "urn:ogc:def:crs:OGC:1.3:CRS84"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.362124135917012, 49.01062717784205]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.437334508302376, 49.004997061308316]
      },
      "properties": {}
    },
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [8.381356011960742, 48.99103162515999]
      },
      "properties": {}
    }
  ]
}'