Trail Router API

Endpoint

https://trailrouter.com/ors/experimentalroutes

Request format

Use GET and supply parameters in the query string. The API calculates walking routes. The defaults below are the API defaults; the website and mobile apps may send different preferences.

Routing parameters

Name	Required or optional	Default	Example	Description
`coordinates`	Required for a new search	None	`-0.157,51.506\\|-0.156,51.506`	Pipe-separated `longitude,latitude` pairs. URL-encode the pipe as `%7C`. Supply one coordinate for a round trip, or at least two for a point-to-point route. Coordinates are snapped to the routable network. Omit this parameter when fetching another page with `next_page_token`.
`roundtrip`	Optional	`false`	`true`	Boolean. When `true`, generate routes that start and finish at the first coordinate; any additional coordinates are ignored. Supply a positive `target_distance` for a round trip. When `false`, route from the first coordinate to the last.
`target_distance`	Required for a round trip; optional otherwise	`0`	`10000`	Desired total distance in metres, as an integer. A positive value requests routes approximately this long. For point-to-point routes, `0` routes through the supplied coordinates without extending the route to a target length. To generate point-to-point alternatives of a desired length, supply two coordinates and a positive distance. The requested distance is a preference, not a guarantee.
`skip_segments`	Optional	Empty (route every segment)	`1,2`	Comma-separated, one-based segment numbers to connect with straight lines instead of routing. For example, `1` skips routing between the first and second coordinates. Useful for working around missing paths in the map. Ignored when `target_distance` is positive.
`green_preference`	Optional	`0`	`0.8`	Number from `0` to `1`. `0` gives no additional preference to greenery; `1` gives the strongest preference to routes through or near green and natural areas. Intermediate values adjust the strength of the preference.
`hills_preference`	Optional	`0`	`-0.5`	Number from `-1` to `1`. Negative values favour flatter routes, positive values favour hillier routes, and `0` gives no preference. Values closer to either endpoint express a stronger preference.
`avoid_repetition`	Optional	`false`	`true`	Boolean. Prefer routes that reuse fewer paths, including fewer out-and-back sections. Some repetition may still be necessary to reach suitable routes or return to the start.
`avoid_unlit_streets`	Optional	`false`	`true`	Boolean. Prefer paths and streets tagged as lit in the map data. This is a routing preference and does not guarantee that the whole route is lit.
`route_count`	Optional	`10`	`5`	Integer from `1` to `20`. Maximum number of routes per page for round-trip and two-coordinate point-to-point searches with a positive `target_distance`. A search can return fewer routes than requested, with at most 20 routes across all pages. Direct routes with `target_distance=0` return a single route.
`next_page_token`	Optional; required to fetch another page	None	Value of `nextPageToken`	Retrieve another page from an existing search. Send the token alone, optionally with `output=json`; do not repeat coordinates, preferences, or `route_count`. The original search parameters and page size are retained. See Pagination.

Output parameters

This page describes the default JSON response.

Name	Required or optional	Default	Example	Description
`output`	Optional	`json`	`json`	Response format: `json` for route results, `gpx` or `kml` to export the first route, or `tbt` for turn-by-turn JSON for the first route. Pagination is available only for `json`.
`instructions`	Optional	`false`	`true`	Boolean. Include turn-by-turn `instructions` in each JSON route. Instructions are generated automatically for `gpx` and `tbt` output.
`locale`	Optional	`en`	`en`	Language code used for generated instructions.
`green_debug`	Optional	`false`	`true`	Boolean. Include `greenDebug` in each route, with the underlying greenery signals, contributions, multiplier factors, OSM way IDs, and segment diagnostics. Omit for normal requests.

Response format

A successful JSON response contains these top-level fields:

Field	Description
`routes`	Array of route objects for the current page.
`hasMoreAvailable`	Boolean indicating whether another page of routes is available for this search.
`nextPageToken`	Opaque token for the next page, or `null` when there are no more pages.

Each route contains the following fields, except where marked conditional:

Field	Description
`distance`	Total route distance in metres.
`duration`	Estimated walking time in milliseconds.
`ascent`	Total elevation gain in metres.
`descent`	Total elevation loss in metres, expressed as a non-negative value.
`weight`	Internal routing cost, incorporating the routing preferences. This is not a duration or a score on a fixed scale.
`geometry`	GeoJSON `LineString` containing the complete route. Each position is `[longitude, latitude, elevation]`, with elevation in metres.
`inputParameters`	Route parameters, including defaults, in camelCase. This is not a verbatim copy of the query string: it contains routing settings such as `targetDistance` and `greenPreference`, but not the input coordinates or output options.
`overriddenParameters`	Object describing settings changed during route construction, such as `avoidRepetition`, and any related construction metadata. Empty when no overrides are recorded.
`waypoints`	Coordinates for the route's waypoints, in `[longitude, latitude, elevation]` order. These may be snapped input points or generated points for editing a suggested route, so they need not match the original input coordinates.
`waypointIndices`	Zero-based indices locating the waypoints within `geometry.coordinates`. Can be `null` when waypoint indices are unavailable.
`wayTypes`	Breakdown of route distance by path or road type, as percentages from `0` to `100`, for example `{"footway": 100.0}`. Can be `null` when path-type details are unavailable.
`greenScore`	Preference-independent greenery score from `0` to `1`. A distance-weighted measure of local woodland, natural and managed green areas, agriculture, inland water, and coastal coverage. Higher values indicate greener surroundings. It is separate from the internal index used to choose routes.
`candidateOsmId`	Present when the route was generated from an OSM feature. Identifies the source feature.
`candidateOsmName`	Present alongside `candidateOsmId`. Name of the source feature; may be `null` if it has no name.
`instructions`	Present when `instructions=true`. Array of turn-by-turn instructions, including text, distance, time, and geometry intervals.
`greenDebug`	Present when `green_debug=true`. Includes the underlying routing Green Index, display coverage and score, applied multiplier, averaged signals and contributions, OSM way IDs, and segment diagnostics.

Pagination

For round-trip and two-coordinate point-to-point searches with a positive target_distance, use route_count to choose the page size. When hasMoreAvailable is true, make another GET request to the same endpoint with only next_page_token set to the returned nextPageToken value. Continue until hasMoreAvailable is false and nextPageToken is null.

Tokens expire 15 minutes after the initial search and may become unavailable earlier if the server evicts cached results or restarts. An expired or unavailable search returns HTTP 410 with error code search_expired; repeat the original request to start a new search. Invalid tokens or requests that combine a token with new search parameters return HTTP 400.

Sample request

This short point-to-point request uses the default routing preferences. curl --data-urlencode encodes the pipe separator automatically.

curl --get 'https://trailrouter.com/ors/experimentalroutes' \
  --data-urlencode 'coordinates=-0.157,51.506|-0.156,51.506' \
  --data-urlencode 'target_distance=0'

Sample response

The following JSON response for the request above was captured on 9 November 2026. It includes the complete route geometry; legacy and internal fields in inputParameters have been omitted. Results may change as map data and routing algorithms are updated.

{
  "routes": [
    {
      "ascent": 4.170000076293945,
      "descent": 0.0,
      "distance": 116.944,
      "weight": 84.199553,
      "duration": 84198,
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-0.157285, 51.506234, 18.24],
          [-0.156903, 51.506414, 19.22],
          [-0.156107, 51.505932, 21.16],
          [-0.156117, 51.505992, 22.41]
        ]
      },
      "inputParameters": {
        "targetDistance": 0.0,
        "greenPreference": 0.0,
        "avoidUnlitStreets": false,
        "hillsPreference": 0.0,
        "avoidRepetition": false,
        "skipSegments": []
      },
      "overriddenParameters": {},
      "waypoints": [
        [-0.1572846701263668, 51.50623407818173, 18.241000175476074],
        [-0.15611714216858635, 51.50599240527535, 22.41100025177002]
      ],
      "wayTypes": {
        "footway": 100.0
      },
      "waypointIndices": [0, 3],
      "greenScore": 0.9
    }
  ],
  "hasMoreAvailable": false,
  "nextPageToken": null
}