Skip to content

Trail Router API


  • Production:
  • Development (London only):

Request format

The only supported method is GET. All parameters should be supplied on the query string.

Name Example Description
coordinates 0.01236,51.482933%7C-0.08901,51.5066 Pipe separated list of lon,lat coordinates. In roundtrip mode only a single coordinate is required. Two or more are required for point-to-point mode.
prefer_green_areas true Boolean indicating a preference for greenery. DEPRECATED. Use green_preference instead. Setting to true means green_preference=0.8
roundtrip true Indicates whether you want the route to start and finish at the first coordinate supplied. When true, all coordinates apart from the first one are ignored.
target_distance 10000 Desired distance in metres. In roundtrip mode, routes will be suggested of approx this length, starting and finishing at coord 0. In point-to-point mode, routes will be suggested of approx this length starting at point 0 and finishing at point n-1. Set target_distance=0 to go direct and avoid having the route extended.
skip_segments 1,2 Optional comma separated list of waypoint indexes which we should draw straight lines between (not calculate a route). Used to work around map errors.
green_preference 1 Double, range {0}..{1}. Indicates how much greenery you want. 1=VeryGreen, 0=NoPreference.
avoid_hills true Boolean indicating whether you wish to avoid hills. DEPRECATED. Use hills_preference instead. Setting avoid_hills=true results in hills_preference=0.5
hills_preference -1 Double, range {-1}..{1}. Indicates how many hills you want. -1=AvoidHills, 0=NoPreference, 1=PreferHills. Can use decimals between, e.g. 0.5=SlightlyPreferHills
avoid_unsafe_streets true Boolean indicating whether you want to avoid primary, secondary and tertiary streets that are not explicitly tagged with footpaths.
avoid_repetition true Boolean indicating whether you want the calculated routes to avoid out-and-back sections
avoid_unlit_streets true Boolean indicating whether you would prefer to use well-lit streets

Response format

The response is a JSON object containing an array of routes. The top level object is as follows:

   "routes": [ ... ]

Each route object has the following fields:

Field Description
distance The distance of the route in metres.
geometry A GeoJSON LineString containing the route itself.
inputParameters Object containing the input parameters as passed into the request.
overriddenParameters Any parameters that the backend API decided to override. Currently only used when avoidReptition=true; we also try with avoidRepetition=false and take the best outcome.
waypoints An array of lon,lat coordinates denoting the waypoints along the route.
waypointIndices The index of each of the waypoint elements inside the geometry LineString.
score Overall route score, taking into account all items below. Range {0}..{1}
greenScore Score for how green the route was, range {0}..{1}. Will default to 1 if route was requested with green_preference=0
hillsScore Score for how well the route matched the desired amount of hills. Range {0}..{1}. When hills_preference<0 (dislike hills), a higher hillsScore means it is less hilly. When hills_preference>0 (prefer hills), a higher hillsScore means it is more hilly. When hills_preference=0, hillsScore will always be 1.
repetitionScore Score for how little repetition there was on the route. Range {0}..{1}. When avoid_repetition=false, repetitionScore will always be 1.
distanceScore Score for how closely the actual distance matched the target_distance input parameter. If target_distance=0 then distanceScore will always be 1.