Skip to content

Routing Options

With the request body parameter options, advanced routing options can be specified for a directions request.

The options parameter is a JSON object, multiple of the here mentioned parameters can be set. For structure refer to the examples.

WARNING

Some of the options below rely on auxiliary data included in the graph, see External storages

Available parameters

options.avoid_borders

String value specifying which borders to avoid. Only for driving-* profiles.

ValueDescription
"all"for no border crossing
"controlled"cross open borders but avoid controlled ones

options.avoid_countries

An integer array of country ids to exclude from routing with driving-* profiles. Can be used together with "avoid_borders": "controlled". The list of countries and application examples can be found in the country list.

"[11,193]" would exclude Austria and Switzerland.

options.avoid_features

A string array of features to avoid. The available features are :

FeatureAvailable for
highwaysdriving-*
tollwaysdriving-*
ferriesdriving-*, cycling-*, foot-*, wheelchair
fordsdriving-*, cycling-*, foot-*
stepscycling-*, foot-*, wheelchair

options.avoid_polygons

Comprises areas to be avoided for the route. Formatted as geojson polygon or geojson multipolygon.

options.profile_params

An object of additional routing parameters for all profiles except driving-car:

options.profile_params.weightings

Weightings will prioritize specified factors over the shortest path. The value is an object that can have the following properties:

  • steepness_difficulty: Integer specifying the fitness level for cycling-* profiles. The preferred gradient increases with the value.

    ValueFitness level
    0Novice
    1Moderate
    2Amateur
    3Pro
  • green: Integer value specifying the Green factor for foot-* profiles.

    ValueGreen factor
    0normal routing
    1prefer ways through green areas over a shorter route
  • quiet: Integer value specifying the Quiet factor for foot-* profiles.

    ValueQuiet factor
    0normal routing
    1prefer quiet ways over a shorter route

options.profile_params.restrictions

An object specifying restrictions for cycling-*, driving-hgv or wheelchairprofiles.

  • for driving-hgv:

    ParameterTypeDescription
    lengthNumberLength restriction in meters.
    widthNumberWidth restriction in meters.
    heightNumberHeight restriction in meters.
    axleloadNumberAxle load restriction in tons.
    weightNumberWeight restriction in tons.
    hazmatBooleanSpecifies whether to use appropriate routing for delivering hazardous goods and avoiding water protected areas. Default is false.
  • for wheelchair:

    ParameterTypeDescription
    surface_typeStringSpecifies the minimum surface type. Default is "cobblestone:flattened".
    track_typeStringSpecifies the minimum quality of the route. Default is "grade1".
    smoothness_typeStringSpecifies the minimum smoothness of the route. Default is "good".
    maximum_sloped_kerbNumberSpecifies the maximum height of the sloped kerb in meters. Values are 0.03, 0.06(default), 0.1 or any.
    maximum_inclineIntegerSpecifies the maximum incline as a percentage. 3, 6(default), 10, 15 or any.
    minimum_widthNumberSpecifies the minimum width of a road in meters.

options.round-trip

An object with specifications of a round-trip:

ParameterTypeDescription
lengthNumberThe target length of the route in m (note that this is a preferred value, but results may be different).
pointsIntegerThe number of points to use on the route. Larger values create more circular routes.
seedIntegerA seed to use for adding randomisation to the overall direction of the generated route (optional).

options.vehicle_type

For profile=driving-hgv only. It is needed for vehicle restrictions to work (see tag filtering). Possible values:

  • hgv
  • bus
  • agricultural
  • delivery
  • forestry
  • goods

Examples

Some options examples in readable and minified JSON form:

for profile=driving-car:

json
{"avoid_features":["ferries","tollways"]}

for profile=cycling-*:

json
{
  "avoid_features": ["steps"],
  "profile_params": {
      "weightings": {
          "steepness_difficulty": 2
      }
  },
  "avoid_polygons": {
    "coordinates": [
      [
        [
          8.683223,
          49.41971
        ],
        [
          8.68322,
          49.41635
        ],
        [
          8.68697,
          49.41635
        ],
        [
          8.68697,
          49.41971
        ],
        [
          8.683223,
          49.41971
        ]
      ]
    ],
    "type": "Polygon"
  }
}
json
{"avoid_features":["steps"],"profile_params":{"weightings":{"steepness_difficulty":2}},"avoid_polygons":{"coordinates":[[[8.683223,49.41971],[8.68322,49.41635],[8.68697,49.41635],[8.68697,49.41971],[8.683223,49.41971]]],"type":"Polygon"}}

for profile=foot-*:

json
{
    "avoid_features": ["fords","ferries"],
    "profile_params": {
        "weightings": {
            "green": {
                "factor": 0.8
              },
            "quiet": {
                "factor": 1.0
            }
        }
    }
}
json
{"avoid_features":["fords","ferries"],"profile_params":{"weightings":{"green":{"factor":0.8},"quiet":{"factor":1.0}}}}

for profile=driving-hgv:

json
{
    "avoid_features": ["ferries","tollways"],
    "profile_params": {
        "restrictions": {
            "length": 30,
            "width": 30,
            "height": 3,
            "axleload": 4,
            "weight": 3,
            "hazmat": true
        }
    }
}
json
{"avoid_features":["ferries","tollways"],"profile_params":{"restrictions":{"length":30,"width":30,"height":3,"axleload":4,"weight":3,"hazmat":true}}}

for profile=wheelchair:

json
{
    "avoid_features": ["ferries","steps"],
    "profile_params": {
        "restrictions": {
            "surface_type": "cobblestone:flattened",
            "track_type": "grade1",
            "smoothness_type": "good",
            "maximum_sloped_kerb": 0.06,
            "maximum_incline": 6
        }
    }
}
json
{"avoid_features":["ferries","steps"],"profile_params":{"restrictions":{"surface_type":"cobblestone:flattened","track_type":"grade1","smoothness_type":"good","maximum_sloped_kerb":0.06,"maximum_incline":6}}}

Border restrictions

Examples for routing options object with border restrictions:

Do not cross country borders at all

json
{"avoid_borders":"all"}

Do not cross controlled borders (i.e. USA - Canada) but allow crossing of open borders (i.e. France - Germany)

json
{"avoid_borders":"controlled"}

Do not route through Austria or Switzerland

json
{"avoid_countries": [11,193]}

Pass open borders but do not cross into Switzerland

json
{"avoid_borders": "controlled","avoid_countries": [193]}