Introduction

This documentation is for v1 of the Route Planning API.

This guide will help you get started with the Route Planning API. To start you will need a test-account or an access token. Get in touch, we will supply you with one asap.

The Route Planning API can:

  • Calculate routes using different profiles, by default for car, pedestrian and bicycle.
  • Calculate recreational routes along cycling or hiking networks.
  • Supply turn-by-turn instructions to implement navigation.

Routing profiles

We supply a few default routing profiles, Bicycle, Car and Pedestrian.

What data is used in the profiles?

The routing profiles only use data from OpenStreetMap to determine behavour and calculate routes.

We use everything OSM has to offer like pedestrian and cycling networks, information about surface quality. We use road classifications as an estimate of traffic intensity and maximum speeds to determine how fast vehicles can go and as an estimate on how fast they will go.

For bicycle safety for example this means we use the road classification as a metric of how big and busy a road is. We use the car maxspeed tags to get an idea on how fast cars can go and we can see in the network if a bicycle path is seperate or attached to the road.

Profiles overview

Bicycle profiles

The bicycle profile has the following options:

  • bicycle: Our default cycling profile that prioritizes speed over everything else.
  • bicycle.comfort: A comfortable route preferring well-paved roads, smaller roads and a bit of scenery at the cost of speed.
  • bicycle.shortest: A profile that prioritizes speed over everything else.
  • bicycle.safety: A defensive route shying away from big roads with lots of cars.
  • bicycle.comfort_safety: A route which aims to be both safe and comfortable at the cost of speed.
  • bicycle.networks: A recreative route following existing cycling networks. Might make longer detours.
  • bicycle.node_network: A recreative route following existing cycle node networks. Might make longer detours.
  • bicycle.cycle_highway: A functional route, preferring cycle_highways or the Brussels Mobility network. If none are availale, will favour speed.
  • bicycle.commute: A functional route which is aimed to commuters. It is a mix of safety, comfort, a pinch of speed and cycle_highway.

We derive the following metrics to build the profiles above:

  • safety: A big road where cars go fast we consider to be unsafe even if there is a cycle lane. When a cycle lane is seperate we consider it as safer. A cyclestreet, towpath and roads used for local access we consider as safer. If a road is only for pedestrians together with cyclists it is also considered safe.
  • comfort: We consider a road comfortable if it is seperate from car traffic, similar to safety. We also use the surface type, when paved and smooth a route will be considered comfortable. We also take into account abandoned railways as pleasant to cycle on.
  • networks: The networks metric takes into account any type of cycling network.
  • node_network: The node networks metric takes into account only the noded cycling networks.
  • cycle_highway: The cycle highway networks metric takes into account only the cycling networks tagged as cycle highways.

STATUS: AVAILABLE

Car profiles

The car profile has the following options:

  • car: Our default car profile. The main metric is time, this focuses on getting somewhere as fast as possible.
  • car.shortest: The main metric is distance, calculates routes that are as short as possible.
  • car.classifications: This profile prefers roads with a higher classification.

STATUS: AVAILABLE

Pedestrian profile

The pedestrian profile is a special case. A pedestrians speed is pretty much constant so there is only one profile:

  • pedestrian: The shortest route.

The pedestrian profiles take into account legal access tags from OSM.

STATUS: AVAILABLE


Formats

We supply a few types of response formats GeoJson, MultiJSON and Mapbox.

GeoJson

GeoJSON is an open standard for geodata and widely supported.

Each segment for the route is a LineString and will have the following properties:

  • distance: The total distance already travelled at the end of the segment in meters.
  • time: The the total time already travelled at the end of the segment in seconds.
  • time_faster: Set to 80% of the time
  • guid: The id of the segment, can be used to combine multiple routes and compare them.

Segments also have details about the roads used, usually taken directly from OpenStreetMap:

  • One or more OpenStreetMap tags, e.g. 'highway=residential','highway=cycleway' or 'route=ferry', oneway=yes, ...
  • 'name' if the road has a name.
  • Other details like access restrictions and cycle networks.

If multiple profiles are given, all the segments will be lumped in together into the geojson. This can be useful when one wants to quickly inspect something with a viewer. However, when working with multiple profiles and geojson, we recommend using MultiJson.

Turn by turn

When turn_by_turn is enabled, maneuver descriptions are included in the segments.

Sample
          
{
    "features": [
        {
            "type": "Feature",
            "name": "ShapeMeta",
            "geometry": {
                "type": "LineString",
                "coordinates": [
                    [
                        4.2379117,
                        51.200317,
                        11
                    ],
                    [
                        4.2379727,
                        51.200367,
                        11
                    ],
                    [
                        4.238337,
                        51.20048,
                        12
                    ],
                    [
                        4.238621,
                        51.20056,
                        12
                    ]
                ]
            },
            "properties": {
                "highway": "path",
                "profile": "bicycle.safety",
                "distance": "231.4",
                "time": "111.07199",
                "guid": "000b04b1-0000-0000-0000-000000000000",
                "maneuver": "Go left on B.",
                "maneuver:type": "turn",
                "maneuver:bearing_before": "260",
                "maneuver:bearing_after": "208",
                "maneuver:turn_type": "left"
            }
        },
        {
            "type": "Feature",
            "name": "ShapeMeta",
            "geometry": {
                "type": "LineString",
                "coordinates": [
                    [
                        4.238621,
                        51.20056,
                        12
                    ],
                    [
                        4.239391,
                        51.19907,
                        12
                    ]
                ]
            },
            "properties": {
                "highway": "footway",
                "profile": "bicycle.safety",
                "guid":	"fff4fb52-ffff-ffff-0000-000000000000",
                "distance": "238.79999",
                "time": "122.91199"
            }
        }
    ]
}
          
        

Maneuvers

If a maneuver is present, it'll contain the following fields:

  • maneuver: a human-readable string describing the maneuver to be made, in the language as specified in the call
  • maneuver:type:stop to indicate that the traveller reached the end, turn to indicate that the traveller has to do something. This will most often be a turn, but a very small turn of only a few degrees is indicated with this as well. To distinguish between those, there it the maneuver:turn_type-field
  • maneuver:turn_type: (only present if the type is turn) a further clarification of what turn is made. This can be used to show an appropriate icon (e.g. an arrow) to the user in the frontend. Possible values are:
    • Left
    • SharpLeft
    • SlightlyLeft
    • Right
    • SharpRight
    • SlightlyRight
    • StraightOn
    • TurnBack
  • maneuver:bearing_before indicates the absolute angle to the north before making the maneuver (thus: going perfectly north is zero, going east is 90, south is 180 and west is 270). Note that this value is only present if the type is turn
  • maneuver:bearing_after indicates the absolute angle to the north after making the maneuver (thus: going perfectly north is zero, going east is 90, south is 180 and west is 270). Note that this value is only present if the type is turn

MultiJson

This option is identical to the above GeoJson response except it allows to return multiple routes for different profiles.

The MultiJSON format is the best way to work with responses containing multiple profiles at once. The returned object will be a JSON object with one key for every profile, where the associated values are the GeoJSON-objects as specified above.

Sample
          
{
    "bicycle.fastest": {
        ... the bicycle.fastest geojson ...
    },
    "bicycle.commute": {
        ... the bicycle.commute geojson ...
    },
    ...
}
          

Mapbox

The API also supports the format too.

If multiple profiles are given, the resulting routes will be found in the 'routes'-part of the returned JSON. The routes are in the same order as the order of appearance in the URL.


API

The API can be tested below along with more formal documentation.