New Routing API Feature: path details and support for avoiding motorway/ferry/toll

Update 2019

Read in our blog about ‘how to use path details’.


We have added some new features to the Routing API that we ask you to try and play with. Please give us feedback and also write us if you have questions.

You can now specify that certain roads should be avoided and to return details of a path, like which parts of the paths have toll restrictions, go through a tunnel or which surface the road has for visualization or navigation purposes.

To see this you can try this example visualization on GraphHopper Maps, where every dot indicates a change for max_speed. Also try to remove the avoid=motorway parameter or use avoid=motorway,trunk to see the difference. Currently these options are available only for the motor vehicles like car, truck, scooter and small_truck.


The following avoid values are possible and can be combined: ferry, bridge, motorway, toll, tunnel and ford.

Example query: /api/1/route?point=50.451821,9.615784&point=50.309515,9.447556&ch.disable=true&avoid=motorway;ferry

The JSON Response is as usual, but the routing engine e.g. tries to avoid motorways and ferries. Please note that if there is no other possibility it will still use them and the parameter ch.disable=true is required.

Path Details

The following path details are possible:

  • street_name: important for navigation applications
  • distance: distance from junction to junction
  • max_speed: This value is in km/h and is also important for navigation applications to print out a warning if the user exceeds these values. A null value for max_speed means that there is no data available from the underlying map data. In Germany there are “unlimited” sections, where we use 150 to indicate this.
  • road_class (motorway, primary, …)
  • road_class_link (true, false)
  • road_environment (ferry, ford, tunnel, …)
  • surface (asphalt, sand, …)
  • lanes: number of lanes
  • toll: currently we support only “no”, “all” or “hgv” if toll is required for hgv vehicles only
  • time: the time details is especially helpful if you track your vehicles and do not want to request our API everytime the vehicles drives a bit further on the already calculated route. The unit is in milliseconds and it states how long it takes for the specific road section

Example query: /api/1/route?point=50.451821,9.615784&point=50.309515,9.447556&details=max_speed&details=street_name

Example JSON response:

{ ... usual JSON ...
  "points": { "coordinates":[[6.72911,49.106228,289],[6.729268,49.106145,285.4],[6.729459,49.105949,285.4],...]},
   "street_name":[[0,2,"Frankfurter Straße"],[2,6,"Zollweg, L 3206"],...]

Where the array content of one path detail list is [from, end, value], e.g. for the first path detail of the street_name it is [0,2,“Frankfurter Straße”], which means that the street name “Frankfurter Straße” refers to the coordinates from index 0 to index 2 (inclusive), ie from lon,lat (6.72911,49.106228) to (6.729459,49.105949). And so these indices work identical to the interval array of the instructions.


The path details feature now also works for the Map Matching API (same URL parameters). You could use it to find out max_speed violations of drivers or create statistics about toll and motorway usage. Ie. it can be used as a post-quality measurement tool.

1 Like

Have added this to the public documentation

1 Like

Would be awesome if you could add restrictions as well, like seasonal access (roads that are closed in winter etc) and border crossings.

1 Like

Got an error when requesting a route with avoid=motorway:,11.707637&point=50.0524,8.5695&elevation=false&locale=de_DE&ch.disable=true&avoid=motorway&points_encoded=true
Error message:

message “Bad Request”
details “java.lang.IllegalArgumentException”
message “No path found due to maximum nodes exceeded 1500000”