Leg-based information - GraphHopper Directions API

Recently we added some new path details: leg_time and leg_distance. This makes it easier to get the time, distance and the geometry per “leg”. A “leg” is a specific part of the route. See the example below and the first leg is from Schwarzkollm (start) to Bröthen (via point) and the second leg is from Bröthen (via point) to Michalken (destination):

The total time, total distance and full geometry is directly accessible in the JSON via path[0].distance, path[0].time and path[0].points:

To better understand the leg information and for the leg geometry we need the “points” entry of the JSON (path[0].points) which is an encoded polyline. To decode it we can use the code of the GraphHopper JavaScript or Java client leading to an array of coordinates (note the order [lon,lat]):

[[lon0, lat0], [lon1, lat1], …]

If the polyline decoding is not possible or if bandwidth does not matter we can specify points_encoded=false and get back a LineString coordinates array:

“points”: { “type”: “LineString”, “coordinates”: [[lon0, lat0], [lon1, lat1], …] }

How to get the information per leg?

To get the coordinates, distance and time for the first leg (from Schwarzkollm to Bröthen) we specify two more path details in the POST request:

"details": ["leg_distance", "leg_time", ...]

In the response JSON the entries “leg_distance” and “leg_time” will appear under “path[0].details”:

"details": {
  ...
  "leg_distance": [
    [ 0, 68, 3504.08],
    [68,113, 2213.46]
  ],
  ...
  "leg_time": [
    [ 0, 68, 892109],
    [68,113, 445463]
  ]
}

This means the first leg from Schwarzkollm (point index 0) to the via point Bröthen (point index 68) has a distance of 3504.08 meters and 892109 milliseconds (i.e. approx. 892 seconds). And with the points array from index 0 to 68 we get the coordinates array of the first leg. Here it does not matter from which entry we pick the indices to determine the leg geometry because “leg_time” and “leg_distance” use the same indices (0, 68, 113).

The same procedure is done for the second leg from the via point Bröthen (point index 68) to Michalken (point index 113): the distance ist 2213.46 meter and 445463 milliseconds i.e. 445 seconds. And if we add all values we will get the same total distance (5717.54m) and time (1337s) that path[0].distance and path[0].time already provided. To get the geometry of the second leg we copy the array from index 68 to 113.

To make retrieving the geometry more explicit we have a look into an …

Example in JavaScript:

// from the Routing API we get by default the encoded polyline format like "an|xHwwhuA......" in path[0].points
// the decode function returns the coordinates in a format like [[lon0, lat0], [lon1, lat1], …]
let coordinates = decode(path[0].points); 

// now get the first leg
let n = 0;
//  For this we use the values of the 0th entry of the leg_time array
let leg_time = path[0].details.leg_time
coordinates.slice(leg_time[n][0], leg_time[n][1]); // In the above example we slice the array from 0 to 68

Happy routing!

Read more about the GraphHopper Directions API in the product overview and our API documentation. Sign up and try everything out in the API Explorer or GraphHopper Maps.