| Forum | GitHub | Maps | Blog

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


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, 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 (if there is no other possibility it will still use them!). Please note that ch.disable=true is required.

Path Details

The following path details are possible:

  • street_name: important for navigation applications
  • 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 negative value for max_speed means that there is no data available from the underlying map. In Germany there are “unlimited” sections, we use 140 instead.
  • road_class (motorway, primary, …)
  • road_environment (ferry, ford, tunnel, …)
  • surface
  • 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.

Tutorial: how to associate path details with 'legs'
Get exact geo coordinates along an entire route with each intersection
Merging of Polylines

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.


Have added this to the public documentation


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


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”

Error: maximum nodes exceeded