Skip to content

Extra Info

When requesting routes, there are a number of "extra info" items that can be requested to give you more information about the route. This info could be things like the road surface, track type, or OpenStreetMap way ID. The list below details which extra info items are available for each profile in the routing provided by https://api.openrouteservice.org.

Specify Extra Info in Request

The desired extra info can be specified in the request body parameter extra_info:

json
"extra_info": [ "steepness", "waytype"]

The following table lists the possible values for the request as well as the keys and possible values in the directions response:

Request Value in extra_infoDescriptionKey in Response $.routes[*].extrasResponse Values
steepnessProvides information about how steep parts of the route aresteepnessSteepness IDs
suitabilityHow suitable the way is based on characteristics of the route and the profilesuitability1 (unsuitable) - 10 (very suitable)
surfaceThe surface covering along the routesurfaceSurface IDs
waycategorySpecific categories of parts of the route (tollways, highways, fords etc.)waycategoryCategory IDs
waytypeTypes of roads and paths that are used in the routewaytypes¹Type IDs
tollwaysAny tollways that the route crosses. Whether a way is marked as tollway depends on profiletollways0 (no tollway) or 1 (tollway)
traildifficultyThe difficulty of parts of the way based on sac or mountain bike scalestraildifficultyDifficulty IDs
osmidThe OpenStreetMap way IDs of the ways the route usesosmId¹
roadaccessrestrictionsInformation about ways that may have access restrictions (e.g. private roads, destination only)roadaccessrestrictionsRestrictions IDs
countryinfoWhich country parts of the way lies incountryinfoCountry IDs
greenHow "green" the parts of the route are (influenced by things like number of trees, parks, rivers etc.)green0 (minimal green-space) - 10 (a lot of green-space)
noiseHow noisy the parts of the route are (influenced by things like proximity to highways)noise0 (quiet) - 10 (noisy)
shadow²How sunny the parts of the route are areshadow0 (completely in the shadow) - 10 (completely in the sun)
csv²Experimental feature: Generic extra information from provided csv file(s)csvcustom values

¹ Note the different keys in request and response!

² No data available in the public openrouteservice hosted by HeiGIT

Extra Info Availability

Some values are not available in all routing profiles:

steepnesssuitabilitysurfacewaycategorywaytypetollwaystraildifficultyosmidroadaccessrestrictionscountryinfogreennoiseshadow
driving-carxxxxxxxxx
driving-hgvxxxxxxxxx
cycling-regularxxxxxx
cycling-mountainxxxxxx
cycling-roadxxxxxx
foot-walkingxxxxxxxxx
foot-hikingxxxxxxxxx
wheelchairxxxxxxx

Extra Info in Responses

The requested extra information can be found in the directions response (JSON endpoints) in the node

jsonpath
$.routes[*].extras

of type object. Each requested extra_info is represented as a nested object entry with the requested value as key, e.g. steepness. Note that some keys in the extras object are different from the requested values, see the table above!

Here one example:

json
"extras": {
  "waytypes": {
    "values": [
      [
        0,
        17,
        3
      ],
      [
        17,
        19,
        1
      ],
      [
        19,
        20,
        3
      ]
    ],
    "summary": [
      {
        "value": 3,
        "distance": 1285.2,
        "amount": 93.93
      },
      {
        "value": 1,
        "distance": 83,
        "amount": 6.07
      }
    ]
  },
  "steepness": {
    "values": [
      [
        0,
        20,
        0
      ]
    ],
    "summary": [
      {
        "value": 0,
        "distance": 1368.2,
        "amount": 100
      }
    ]
  }
}

The values of each entry have the same structure: Objects with the entries values and summary:

values

A list of integer arrays with length 3 representing a contiguous section of the calculated route with the same value of the requested information type. The three values of each list have the following semantics:

  1. Index of the way point starting the section
  2. Index of the way point at the end of the section
  3. Value of the extra info measure (waytype, steepness etc.) for this section

In the example above, the calculated route has three sections with different waytypes:

  • waypoints 0-17: waytype=3
  • waypoints 17-19: waytype=1
  • waypoints 19-20: waytype=3

and only one section (i.e. the whole route) from waypoint 0-20 with steepness=0.

summary

A list of objects with the entries value, distance, amount summarizing the total length (distance) and relative length (amount) of all segments with a given value of the extra info unit.

In the example above, all sections with waytype=3 have a summarized length of 1285.2 m which is 93.93% of the calculated route and 100% of the route have steepness=0.