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

Routing

The basic functionality of the SmartMaps API also includes the ability to calculate arbitrary routes.

To be able to calculate a route, at least the start and end points of the route are required.

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/route

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

Route

Parameter

This type allows a route calculation between two coordinates with optional intermediate coordinates.

The parameters are included in the body, of the POST request as JSON.
{
    "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": {}
        }
    ]
}
Name Description Data type Default value
type Specifies what type it is according to geoJSON. string
routingparams.type Must be set to ROUTE. string
routingparams.isoLocale Allows you to set the language of the route instructions. 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
routingparams.speedProfile One of the valid speed profiles from the list:
  • FAST - Fast car
  • SLOW - Slow car
  • BICYCLE - Bicycle
  • PEDESTRIAN - Pedestrian
 string
routingparams.routingTimeMode Defines how the time is calculated:
  • ARRIVAL - Arrival time
  • DEPARTURE - Departure time
 string
authentication.channel Any desired string that is logged and used to identify the call later. It can be freely chosen. string
crs.type Specifies the type of the coordinate reference system. string
crs.properties.name Specifies the name of the coordinate reference system. string
features Include more than one point. First is the starting point, intermediate points and last one the destination point. POINT[]

Return

{
    "properties": {
        "id": "e1ae0856-b54a-47ba-9112-093db70e8668",
        "distance": 15460.0,
        "duration": 1166.0,
        "exception": {
            "errCode": "",
            "publicReport": ""
        }
    },
    "features": [
        {
            "properties": null,
            "geometry": {
                "coordinates": [
                    [
                        8.36214,
                        49.01067
                    ],
                    ...
                    [
                        8.38134,
                        48.99101
                    ]
                ],
                "bbox": [
                    8.36214,
                    48.98901,
                    8.43766,
                    49.01067
                ],
                "type": "LineString"
            },
            "bbox": [
                8.36214,
                48.98901,
                8.43766,
                49.01067
            ],
            "type": "Feature"
        },
        {
            "properties": {
                "nextDistance": 0.0,
                "nextDuration": 0.0,
                "direction": null,
                "trackSection": "Sophienstraße",
                "compass": "102",
                "navImage": "Start",
                "description": "Fahren Sie Richtung Osten auf Sophienstraße",
                "totalDistance": 0.0,
                "totalTime": 0.0
            },
            "geometry": {
                "coordinates": [
                    8.36214,
                    49.01067
                ],
                "bbox": [
                    8.36214,
                    49.01067,
                    8.36214,
                    49.01067
                ],
                "type": "Point"
            },
            "type": "Feature"
        },
        ...
        {
            "properties": {
                "nextDistance": 255.0,
                "nextDuration": 38.0,
                "direction": null,
                "trackSection": "Neue-Anlage-Straße",
                "compass": "0",
                "navImage": "End",
                "description": "Sie haben Ihr zweites Ziel erreicht",
                "totalDistance": 15449.0,
                "totalTime": 1157.0
            },
            "geometry": {
                "coordinates": [
                    8.38134,
                    48.99101
                ],
                "bbox": [
                    8.38134,
                    48.99101,
                    8.38134,
                    48.99101
                ],
                "type": "Point"
            },
            "type": "Feature"
        }
    ],
    "type": "FeatureCollection"
}
Name Description Data type
properties.id Specifies the ID of the routing request. string
properties.distance Specifies the total distance in meters for the routing request. double
properties.duration Specifies the travel time in seconds for the routing request. double
properties.exception.errCode Specifies an error code when an error occurs. string
properties.exception.publicReport Specifies, if an error occurs, an error description. string
features[].properties Reserved for future functions. ?{}
features[].properties.geometry.coordinates Represents coordinates of a route (type=LineString) or directions descriptions(type=Point). double[]
features[].properties.geometry.bbox Specifies a rectangle in which the feature is located. double[]
features[].properties.geometry.type Defines what kind of geometric object it is.
  • LineString - Represents the path as a line
  • Point - Represents the places where there are directions descriptions.
 string
features[].properties.bbox Specifies a rectangle in which all returned features are located. double[]
features[].properties.type Indicates what type it is according to geoJSON. string
features[].properties.nextDistance Indicates in how many meters the routing instruction is away from the previous one. double
features[].properties.nextDuration Indicates how many seconds it takes to reach, from the previous routing instruction under normal traffic situation. double
features[].properties.direction Indicates the direction. Number
features[].properties.trackSection Specifies the street you are on after executing the directions description. ?string
features[].properties.compass Indicates the direction to travel from 0-360 degrees. ?number
features[].properties.navImage Suggests an image for navigation. Possible images are: ArrowForward, ArrowLeft, ArrowRight, blank, CircleIn, CircleOut, uturn string
features[].properties.description Indicates the directions description. string
features[].properties.totalDistance Indicates the distance traveled so far in meters. double
features[].properties.totalTime Indicates the total time driven so far in seconds. double
type Indicates what type it is according to geoJSON. string

Matrix

This type allows to calculate the distance and travel time between several coordinates and one coordinate.

Parameter

The parameters are included in the body, of the POST request as JSON.
{
    "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
                    ]
                ]
            }
        }
    ]
}
Name Description Data type Default value
type Specifies what type it is according to geoJSON. string
routingparams.type Must be set to MATRIX. 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
routingparams.speedProfile One of the valid speed profiles from the list:
  • FAST - Fast car
  • SLOW - Slow car
  • BICYCLE - Bicycle
  • PEDESTRIAN - Pedestrian
 string
routingparams.routingTimeMode Defines how the time is calculated:
  • ARRIVAL - Arrival time
  • DEPARTURE - Departure time
 string
authentication.channel Any desired string that is logged and used to identify the call later. It can be freely chosen. string
crs.type Specifies the type of the coordinate reference system. string
crs.properties.name Specifies the name of the coordinate reference system. string
features[0] Specifies from one point. This is the starting point. POINT
features[1] Specifies several points. These are the end points. MULTIPOINT

Return

{
    "properties": {
        "id": null,
        "distance": 0.0,
        "duration": 0.0,
        "exception": {
            "errCode": "",
            "publicReport": ""
        }
    },
    "features": [
        {
            "properties": {
                "routingDestinations": [
                    {
                        "distanceInMeters": 5560.0,
                        "timeInSeconds": 551.0
                    },
                    {
                        "distanceInMeters": 6440.0,
                        "timeInSeconds": 535.0
                    },
                    {
                        "distanceInMeters": 4074.0,
                        "timeInSeconds": 372.0
                    }
                ]
            },
            "geometry": {
                "coordinates": [
                    8.33195,
                    49.01603
                ],
                "bbox": [
                    8.33195,
                    49.01603,
                    8.33195,
                    49.01603
                ],
                "type": "Point"
            },
            "type": "Feature"
        }
    ],
    "type": "FeatureCollection"
}
Name Description Data type
properties.id Specifies the ID of the routing request. ?string
properties.distance Not used. double
properties.duration Not used. double
properties.exception.errCode Specifies an error code when an error occurs string
properties.exception.publicReport Specifies, if an error occurs, an error description. string
features[].properties Reserved for future functions. ?{}
features[].properties. routingDestinations.distanceInMeters Specifies the total distance in meters for the start point to one of the end points. Order of the endpoints corresponds to what was passed to features[1] in the request. double
features[].properties. routingDestinations.timeInSeconds Specifies the travel time in seconds for the start point to one of the end points. Order of the endpoints corresponds to what was passed to features[1] in the request. double
features[].geometry Specifies the starting point. POINT
type Indicates what type it is according to geoJSON. string

Trip

This type enables a calculation of the optimal approach route between a start destination and several destinations.

Parameter

The parameters are included in the body, of the POST request as JSON.
{
    "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
                    ]
                ]
            }
        }
    ]
}
Name Description Data type Default value
type Specifies what type it is according to geoJSON. string
routingparams.type Must be set to TRIP. string
routingparams.routingRoundTrip When true, then the starting point is also the final destination. boolean
routingparams.isoLocale Allows you to set the language of the route instructions. string
routingparams.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
routingparams.speedProfile One of the valid speed profiles from the list:
  • FAST - Fast car
  • SLOW - Slow car
  • BICYCLE - Bicycle
  • PEDESTRIAN - Pedestrian
 string
routingparams.routingTimeMode Defines how the time is calculated:
  • ARRIVAL - Arrival time
  • DEPARTURE - Departure time
 string
authentication.channel Any desired string that is logged and used to identify the call later. It can be freely chosen. string
crs.type Specifies the type of the coordinate reference system. string
crs.properties.name Specifies the name of the coordinate reference system. string
features[] Passing more than one point as multipoint, see also GeoJSON. The first point is the starting point. All other points are intermediate points. MULTIPOINT

Return

{
    "properties": {
        "id": null,
        "distance": 38817.0,
        "duration": 2070.0,
        "exception": {
            "errCode": "",
            "publicReport": ""
        }
    },
    "features": [
        {
            "properties": null,
            "geometry": {
                "coordinates": [
                    [
                        8.10359,
                        49.00892
                    ],
                    ...
                ],
                "bbox": [
                    8.08453,
                    48.98901,
                    8.45721,
                    49.05682
                ],
                "type": "LineString"
            },
            "bbox": [
                8.08453,
                48.98901,
                8.45721,
                49.05682
            ],
            "type": "Feature"
        },
        {
            "properties": {
                "nextDistance": 0.0,
                "nextDuration": 0.0,
                "direction": "left",
                "trackSection": "",
                "compass": "358",
                "navImage": "Start",
                "description": "Fahren Sie Richtung Norden auf K 23",
                "totalDistance": 0.0,
                "totalTime": 0.0
            },
            "geometry": {
                "coordinates": [
                    8.10359,
                    49.00891
                ],
                "bbox": [
                    8.10359,
                    49.00891,
                    8.10359,
                    49.00891
                ],
                "type": "Point"
            },
            "type": "Feature"
        },
        ...
    ],
    "type": "FeatureCollection"
}
Name Description Data type
properties.id Specifies the ID of the routing request. string
properties.distance Specifies the total distance in meters for the routing request. double
properties.duration Specifies the travel time in seconds for the routing request. double
properties.exception.errCode Specifies an error code when an error occurs. string
properties.exception.publicReport Specifies, if an error occurs, an error description. string
features[].properties Reserved for future functions. ?{}
features[].properties.geometry.coordinates Represents coordinates of a route (type=LineString) or directions descriptions(type=Point). double[]
features[].properties.geometry.bbox Specifies a rectangle in which the feature is located. double[]
features[].properties.geometry.type Defines what kind of geometric object it is.
  • LineString - Represents the path as a line
  • Point - Represents the places where there are directions descriptions.
 string
features[].properties.bbox Specifies a rectangle in which all returned features are located. double[]
features[].properties.type Indicates what type it is according to geoJSON. string
features[].properties.nextDistance Indicates in how many meters the routing instruction is away from the previous one. double
features[].properties.nextDuration Indicates how many seconds it takes to reach, from the previous routing instruction under normal traffic situation. double
features[].properties.direction Indicates the direction. Number
features[].properties.trackSection Specifies the street you are on after executing the directions description. ?string
features[].properties.compass Indicates the direction to travel from 0-360 degrees. ?number
features[].properties.navImage Suggests an image for navigation. Possible images are: ArrowForward, ArrowLeft, ArrowRight, blank, CircleIn, CircleOut, uturn string
features[].properties.description Indicates the directions description. string
features[].properties.totalDistance Indicates the distance traveled so far in meters. double
features[].properties.totalTime Indicates the total time driven so far in seconds. double
type Indicates what type it is according to geoJSON. string

Isochrone

Allows to calculate the area covered by a given travel time or travel distance.

Parameter

The parameters are included in the body, of the POST request as JSON.
{
    "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": {}
        }
    ]
}
Name Description Data type Default value
type Specifies what type it is according to geoJSON. string
routingparams.type Must be set to ISOCHRONE. string
routingparams.timeInMinutes Time in minutes in which the object can move. Can take values from >0 to 60. Either timeInMinutes or distanceInMeters can be passed. ?double null
routingparams.distanceInMeters Distance in meters in which the object can move. Either timeInMinutes or distanceInMeters can be passed. ?double null
routingparams.isochroneGrid Defines the fineness of the polygon that will be calculated. The higher the values, the finer the polygon. Can take values from 35 to 150. Number
routingparams.speedProfile One of the valid speed profiles from the list:
  • FAST - Fast car
  • SLOW - Slow car
  • BICYCLE - Bicycle
  • PEDESTRIAN - Pedestrian
 string
routingparams.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
routingparams.routingTimeMode Defines how the time is calculated:
  • ARRIVAL - Arrival time
  • DEPARTURE - Departure time
 string
authentication.channel Any desired string that is logged and used to identify the call later. It can be freely chosen. string
crs.type Specifies the type of the coordinate reference system. string
crs.properties.name Specifies the name of the coordinate reference system. string
features A point that serves as a starting point. POINT

Return

{
    "properties": {
        "id": null,
        "distance": 0.0,
        "duration": 0.0,
        "exception": {
            "errCode": "",
            "publicReport": ""
        }
    },
    "features": [
        {
            "properties": {
                "featureType": "ISOCHRONE_OUTLINE_POLYGON"
            },
            "geometry": {
                "coordinates": [
                    [
                        [
                            7.25311,
                            49.29825
                        ],
                        ...
                        [
                            7.25311,
                            49.29825
                        ]
                    ]
                ],
                "type": "Polygon"
            },
            "bbox": [
                7.24636,
                48.1835,
                9.70117,
                49.89793
            ],
            "type": "Feature"
        },
        {
            "properties": null,
            "geometry": {
                "coordinates": [
                    8.39406,
                    48.99306
                ],
                "bbox": [
                    8.39406,
                    48.99306,
                    8.39406,
                    48.99306
                ],
                "type": "Point"
            },
            "type": "Feature"
        }
    ],
    "type": "FeatureCollection"
}
Name Description Data type
properties.id Specifies the ID of the routing request. ?string
properties.distance Indicates which distance was taken into account for the calculation. double
properties.duration Indicates which travel time was taken into account for calculation. double
properties.exception.errCode Specifies an error code when an error occurs. string
properties.exception.publicReport Specifies, if an error occurs, an error description. string
features[].properties.featureType Defines what kind of geometric object it is. ?{}
features[0] Returns a polygon representing the covered area. POLYGON
features[1] Returns the origin point. POINT
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/route?systemPartner={{system_Partner}}&securityID={{security_id}}' \
--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": {}
        }
    ]
}'

Error

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