Cyclers Navigate Docs

Routing API

1 Introduction

This document describes the Cyclers Navigate Routing API (the Routing API hereafter), provided by Umotional, for bicycle route planning. Cyclers Navigate is a bicycle route planning engine capable of planning high-quality routes of different types and criteria. The Routing API exposes the Cyclers engine’s functionality for integration into partners’ products and services.

The Routing API produces a set of routes from the origin to the destination based on specified parameters. For a given request, the Routing API typically returns five routes. The proposed routes are calculated to be geospatially diverse (that is, not overlapping) and to represent different trade-offs between route duration (highly correlated with route distance) and overall Match with user-defined preferences and route factors. User preferences are defined by the selected Routing Profile and can be fine-tuned using Factor Preferences. For example, setting profile to ROAD_CYCLING and traffic preference to REQUIRE_LOW makes the API prefer lower-traffic roads, even if that leads to a longer route than the profile default.

The Routing API can be accessed through the endpoint

POST /v7/routing

The HTTPS protocol is mandatory when calling the Routing API. JSON is used for both requests and responses. GZIP compression is used for requests and responses to minimize data transfer between backend and client.

1.1 Match Model

The Match concept represents a fundamental metric that quantifies how well a planned route corresponds to the user-defined preferences. It serves as both an internal optimization function for the routing engine and an interpretable value for the user.

Match (0-100%) expresses the correspondence between the route (or its parts) and the user’s settings, specifically the selected Routing Profile and detailed Factor Preferences.

• Route Match: A single comparison value for the entire route, exposed in route.stats.userSettingsMatch, allows easy ranking and comparison of route alternatives.

• Segment Match: The match model also evaluates partial elements of the route. Each route segment in GeoJson contains a preferencesMatch field, which evaluates that specific part strictly based on the user’s preferences.

This granular evaluation enables powerful visualization. Applications can use the segment match values to color-code the route on the map, providing immediate visual feedback on how well each section fits the user’s needs.

The segments are colored according to the legend above, distinguishing between good matches (green), partial matches (yellow/orange) and bad matches (red).

2 Example Uses

This section provides examples of the most common Routing API use cases. The full specification of the API is further described in Section 3 Routing API Specification.

2.1 Point-to-Point Routes

Calculating point-to-point routes is the simplest and default use case of the Routing API. In this case, a set of routes from a given origin to a given destination is calculated.

A sample request payload is shown below:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.090438, "lon": 14.368958}
  },
  "settings": {
    "profile": "CASUAL_CYCLING",
    "factorPreferences": {}
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.2 Point-to-Point Routes with Waypoints

Point-to-point routes can be constrained to pass through specific waypoints by specifying waypoint locations in the waypoints field of the request. By default, planned routes pass the waypoints in the order provided.

To achieve this, the request must be specified as follows:

• Specify desired points of interest in the waypoints field.

A sample request payload is shown below:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.090438, "lon": 14.368958}
  },
  "waypoints": [
    {
      "locationType": "POINT",
      "point": {"lat": 50.110808, "lon": 14.396338}
    }
  ],
  "settings": {
    "profile": "CASUAL_CYCLING",
    "factorPreferences": {}
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.3 Order-Optimized Multi-Waypoint Routes

The Routing API can also plan routes that visit multiple points of interest in an optimized order.

To achieve this, the request must be specified as follows:

• Specify desired points of interest in the waypoints field.

• Set optimizeWaypointOrder to true.

The maximum number of allowed points of interest is 15.

A sample request payload is shown below:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "waypoints": [
    {
      "locationType": "POINT",
      "point": {"lat": 50.081327, "lon": 14.413480}
    },
    {
      "locationType": "POINT",
      "point": {"lat": 50.079761, "lon": 14.429744}
    },
    {
      "locationType": "POINT",
      "point": {"lat": 50.086951, "lon": 14.420524}
    },
    {
      "locationType": "POINT",
      "point": {"lat": 50.075447, "lon": 14.414101}
    },
    {
      "locationType": "POINT",
      "point": {"lat": 50.086469, "lon": 14.411515}
    }
  ],
  "settings": {
    "profile": "CASUAL_CYCLING",
    "factorPreferences": {},
    "optimizeWaypointOrder": true
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.4 Circular Routes

The Routing API can also plan circular routes with a desired length. To achieve this, the request must be specified as follows:

• origin must be equal to destination.

• settings.desiredLengthMeters must contain the desired route length in meters as an integer.

A sample request payload is shown below:

{
  "client":"IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "settings":{
    "profile": "CASUAL_CYCLING",
    "factorPreferences": {},
    "desiredLengthMeters": 5000
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.5 How to Customize Routes

The Routing API allows extensive route customization to match specific user needs. This customization is based on two main pillars:

1. Routing Profiles: These define the general character of the route (e.g., road cycling vs. mountain biking) and determine the default Factor Preferences.

2. Factor Preferences: These allow you to set specific preferences for individual factors (e.g., surface quality, traffic stress, or hilliness), overriding the defaults set by the selected profile.

Available Routing Profiles

The following profiles are available in settings.profile:

• CASUAL_CYCLING: Ideal for casual riders seeking leisurely routes without steep climbs, poor surfaces, or heavy traffic.

• COMMUTE_CYCLING: Ideal for transport purposes - prioritizes distance and time efficiency over other aspects.

• MOUNTAIN_BIKING: Tailored for adventure riders who enjoy taking their bikes on trails and unpaved surfaces.

• GRAVEL_RIDING: Designed for cyclists who are as happy on low-traffic asphalt as on well passable unpaved roads.

• ROAD_CYCLING: Intended for road cyclists who prefer smooth surfaces, even if it means encountering cars.

• SAFE_CYCLING: Designed for safety-conscious riders who prioritize avoiding cars and technically challenging segments.

• WALKING: Designed for walkers - uses safe and walkable paths including sidewalks, trails, and pedestrian areas.

Note

E-bike Variants: All profiles (except WALKING) are also available as E-bike variants. These are prefixed with E_ (e.g., E_ROAD_CYCLING, E_MOUNTAIN_BIKING). When using an E-bike profile, remember to also select a corresponding ELECTRIC_* bike type.

Factor Preferences

To customize a route beyond profile defaults, use the factorPreferences object inside settings. Any preference specified here acts as an override for that specific factor, while all other factors remain at their profile-defined defaults.

For example, to plan a road cycling route while strictly avoiding steep climbs (which might otherwise be acceptable in a standard road profile), select ROAD_CYCLING and add a hilliness preference.

For full technical details of settings.profile and settings.factorPreferences, including all supported values, see Section 3.2 Request Settings.

2.5.1 Minimal Profile-Based Request

settings.profile and settings.factorPreferences are required. Use "factorPreferences": {} to keep profile defaults.

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.090438, "lon": 14.368958}
  },
  "settings": {
    "profile": "CASUAL_CYCLING",
    "bikeType": "HYBRID_BIKE",
    "factorPreferences": {}
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.5.2 Mountain Biking

Example with explicit factor overrides for mountain biking:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "settings": {
    "profile": "MOUNTAIN_BIKING",
    "bikeType": "MOUNTAIN_BIKE",
    "factorPreferences": {
      "surface": {"preference": "PREFER_UNPAVED"},
      "hilliness": {"preference": "AVOID_STEEP_CLIMBS"},
      "scenic": {"preference": "PREFER_SCENIC"},
      "stairs": {"preference": "STRICTLY_AVOID"}
    }
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.5.3 Road Cycling

Example emphasizing smooth paved roads and low traffic:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "settings": {
    "profile": "ROAD_CYCLING",
    "bikeType": "ROAD_BIKE",
    "factorPreferences": {
      "surface": {"preference": "REQUIRE_PAVED"},
      "traffic": {"preference": "PREFER_LOW"},
      "hilliness": {"preference": "AVOID_STEEP_CLIMBS"}
    }
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.5.4 Safe Cycling

Example prioritizing maximum safety and strict legal behavior:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "settings": {
    "profile": "SAFE_CYCLING",
    "bikeType": "HYBRID_BIKE",
    "factorPreferences": {
      "traffic": {"preference": "TRAFFIC_FREE"},
      "pavements": {"preference": "STRICTLY_AVOID"},
      "counterDirection": {"preference": "STRICTLY_AVOID"}
    }
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.5.5 Walking

Example for pedestrian routing:

{
  "client": "IOS",
  "origin": {
    "locationType": "POINT",
    "point": {"lat": 50.105827, "lon": 14.415478}
  },
  "destination": {
    "locationType": "POINT",
    "point": {"lat": 50.090438, "lon": 14.368958}
  },
  "settings": {
    "profile": "WALKING",
    "bikeType": "WALK",
    "factorPreferences": {
      "traffic": {"preference": "TRAFFIC_FREE"},
      "scenic": {"preference": "PREFER_SCENIC"},
      "stairs": {"preference": "TOLERATE"},
      "pavements": {"preference": "PREFER"}
    }
  },
  "key": "<YOUR ROUTING API KEY>"
}

2.5.6 Commute and Gravel Presets

Compact settings snippets for the remaining cycling presets:

{
  "settings": {
    "profile": "COMMUTE_CYCLING",
    "bikeType": "HYBRID_BIKE",
    "factorPreferences": {}
  }
}

{
  "settings": {
    "profile": "GRAVEL_RIDING",
    "bikeType": "GRAVEL_BIKE",
    "factorPreferences": {}
  }
}

3 Routing API Specification

3.1 Request

The Routing API request object should be sent in the body of an HTTP POST request to the endpoint specified above.

The request parameters below define the desired characteristics of the planned routes.

Required Parameters

origin:

The required origin location object.

Example:

{
  "locationType": "POINT",
  "point": {
    "lat": 50.767001,
    "lon": 15.057661
  }
}

destination:

The required destination location object.

Example:

{
  "locationType": "POINT",
  "point": {
    "lat": 50.785911,
    "lon": 15.063445
  }
}

client:

The client name. Possible values are WEB, ANDROID, IOS.

settings:

Required settings object. The fields settings.profile and settings.factorPreferences are mandatory. settings.factorPreferences can be an empty object {}, but it must be present; otherwise deprecated routing is used. Details of all settings fields are described in Section 3.2 Request Settings.

key:

The key that provides access to the Routing API on behalf of a user. Each user of the Routing API has a unique key.

Note

A key is needed to access the Routing API. The key must be inserted into each request.

Optional Parameters

waypoints:

List of waypoint location objects through which planned routes must pass.

Example:

[
  {
    "locationType": "POINT",
    "point": {
      "lat": 50.785911,
      "lon": 15.063445
    }
  },
  {
    "locationType": "POINT",
    "point": {
      "lat": 50.767001,
      "lon": 15.057661
    }
  }
]

3.2 Request Settings

The settings object specifies preferred route characteristics and includes two groups of parameters: profile-based route settings and additional route settings.

Profile-based route settings define the user’s routing intent and preferences for route-choice factors. They include routing profile (required), bikeType (optional, recommended for better travel-time personalization), and factorPreferences (required object; may be empty), which adjusts preferences for factors such as traffic, hilliness, surface smoothness, pavements, and stairs, as described in Section 2.5 How to Customize Routes. These parameters also define the preference model against which Match is computed (see Section 1.1 Match Model).

Additional route settings define explicit planning requirements, such as desired route length (desiredLengthMeters), waypoint order optimization (optimizeWaypointOrder), and whether to include route GeoJSON (addRouteGeoJson).

"settings": {
  "profile": "CASUAL_CYCLING",
  "bikeType": "HYBRID_BIKE",
  "factorPreferences": {
    "traffic": {"preference": "REQUIRE_LOW"},
    "surface": {"preference": "PREFER_PAVED"}
  },
  "optimizeWaypointOrder": true,
  "desiredLengthMeters": 10000,
  "addRouteGeoJson": false
}

Profile-Based Route Settings

profile:

Required routing profile preset.

Standard profile values: CASUAL_CYCLING, COMMUTE_CYCLING, MOUNTAIN_BIKING, GRAVEL_RIDING, ROAD_CYCLING, SAFE_CYCLING, WALKING.

E-bike profile values: E_CASUAL_CYCLING, E_COMMUTE_CYCLING, E_MOUNTAIN_BIKING, E_GRAVEL_RIDING, E_ROAD_CYCLING, E_SAFE_CYCLING.

bikeType:

Used for travel time personalization and vehicle-specific constraints.

Standard values: WALK, CITY_BIKE, ROAD_BIKE, MOUNTAIN_BIKE, HYBRID_BIKE, FOLDING_BIKE, CARGO_BIKE, FIXIE_BIKE, GRAVEL_BIKE, RECUMBENT_BIKE, SCOOTER, BIG_WHEEL_SCOOTER.

Electric values: ELECTRIC_BIKE, ELECTRIC_CITY_BIKE, ELECTRIC_ROAD_BIKE, ELECTRIC_MOUNTAIN_BIKE, ELECTRIC_FOLDING_BIKE, ELECTRIC_CARGO_BIKE, ELECTRIC_FIXIE_BIKE, ELECTRIC_HYBRID_BIKE, ELECTRIC_GRAVEL_BIKE, ELECTRIC_RECUMBENT_BIKE, ELECTRIC_SCOOTER.

factorPreferences:

Required object for profile defaults and overrides. It must be present in every request and can be empty ({}) when no overrides are needed. If omitted, deprecated routing is used. The object is keyed by factor ID; each factor contains {"preference": "<VALUE>"}.

Structure:

"factorPreferences": {
  "<factorId>": {
    "preference": "<VALUE>"
  }
}

Supported factor IDs: traffic, surface, hilliness, scenic, track, stairs, pavements, counterDirection.

Allowed factor preferences:

traffic

• TOLERATE_HIGH = High traffic is not a problem - other factors determine the route.

• PREFER_LOW = Prefer low traffic, but I can handle moderate to high traffic.

• REQUIRE_LOW = Require low traffic, moderate is acceptable only if necessary.

• TRAFFIC_FREE = Require segments without car traffic - ideal for beginners and children.

surface

• REQUIRE_PAVED = Require a smooth and high-quality paved surface - ideal for road bikes.

• PREFER_PAVED = Paved surface is preferred, but I can handle slightly rough sections.

• NEUTRAL = Surface is not a priority, but I want to avoid the worst.

• PREFER_UNPAVED = Prefer natural, well-rideable segments - ideal for mountain biking.

• SINGLE_TRACK = Seek narrow unpaved trails - perfect for an adventurous ride.

hilliness

• REQUIRE_FLAT = Require completely flat terrain with no hills or steep sections.

• PREFER_FLAT = Prefer flat terrain, but mild climbs are not a problem.

• AVOID_STEEP_CLIMBS = Climbs are acceptable as long as they are not too steep.

• PREFER_HILLS = Prefer hills over flat terrain - ideal for a sport ride.

scenic

• NOT_CONSIDERED = Surroundings do not matter - other factors determine the route.

• PREFER_SCENIC = Prefer sections through natural environment.

• REQUIRE_SCENIC = Require sections through natural environment away from busy roads.

track

• NOT_CONSIDERED = Track width is not considered.

• REQUIRE_DUAL = Favors wide paths that allow side-by-side riding or riding with a trailer. Excludes singletracks and narrow paths.

stairs

• AVOID_IF_REASONABLE = Prefer to avoid stairs, but short stairs segments may be used if no reasonable alternative exists.

• STRICTLY_AVOID = Completely avoid stairs; routes must not include any stairs segments.

• TOLERATE = Stairs are acceptable and do not need to be avoided.

pavements

• AVOID_IF_REASONABLE = Prefer to avoid pavements/sidewalks if reasonable alternatives exist.

• STRICTLY_AVOID = Completely avoid pavements; routes must not include pedestrian-only segments.

• PREFER = Prefer pavements where allowed and appropriate, useful for walking and safer alternatives.

counterDirection

• AVOID_IF_REASONABLE = Prefer to avoid traveling opposite to allowed traffic direction, but allow it when no better option exists.

• STRICTLY_AVOID = Completely avoid traveling against allowed traffic direction, for example against one-way streets.

Additional Route Settings

optimizeWaypointOrder:

Specifies whether the route planning engine should optimize the order in which waypoints are visited.

Possible values:

false = Order is not optimized, i.e., the waypoints are visited in the order specified (default).

true = Order is optimized, i.e., the waypoints are visited in the order minimizing the overall travel time.

desiredLengthMeters:

Specifies the desired route length in meters returned by the route planning engine. The desired route length is approximate. The actual length may differ.

addRouteGeoJson:

Boolean parameter indicating whether the route object in the response should also contain a GeoJSON representation. See the route representation in Section 3.9 Route GeoJSON. Default value is false.

3.3 Response

The Routing API returns a response object according to the specified request (see Section 3.1 Request).

The response consists primarily of a set of routes found by the routing engine. Each route represents one suggested way to travel between the locations specified in the request.

Required fields

id:

Unique ID of the routing response.

request:

The corresponding routing request.

creationTimestamp:

ISO-8601 timestamp of response creation, e.g., 2019-11-01T16:00:00.000+02:00.

status:

Routing response status. Each routing response status is tied to a corresponding HTTP response status code.

Possible values:

OK = Indicates the response contains a valid result.

INVALID_REQUEST (HTTP 400) = Indicates the provided request was invalid. Common causes include an invalid parameter or parameter value.

MAX_WAYPOINTS_EXCEEDED (HTTP 400) = Indicates too many waypoints were provided in the request.

NOT_AUTHORIZED (HTTP 401) = Indicates the request could not be processed due to authorization. Try again with a valid key.

FORBIDDEN (HTTP 403) = Indicates the request could not be processed due to authorization. The routing zone is not supported for the given key.

ROUTE_NOT_FOUND (HTTP 404) = Indicates no route could be found between the origin and destination given the routing settings.

LOCATION_NOT_FOUND (HTTP 404) = Indicates at least one location in origin, destination, or waypoints is outside any routing zone.

CROSS_ZONE_UNSUPPORTED (HTTP 404) = Indicates not all locations in origin, destination, or waypoints are inside the same routing zone.

LIMIT_EXCEEDS (HTTP 429) = Indicates the request could not be processed due to endpoint rate limiting. Try again later.

SERVER_ERROR (HTTP 500) = Indicates the request could not be processed due to a server error.

SERVICE_UNAVAILABLE (HTTP 503) = Indicates the request could not be processed because the service is temporarily unavailable. Try again later.

routes:

List of found routes, when status is OK; otherwise this field is an empty list. Details of route fields are described in Section 3.4 Route.

Optional fields

invalidRequest:

Invalid request for which this response was created (in case of INVALID_REQUEST status).

errorMessage:

Message with specific information about the error cause.

Note

The response can contain additional fields not documented here. These are not relevant for bike route planning and should be ignored.

Sample valid response JSON:

{
  "id": "5dbb1131e21b84000723d794",
  "request": {
    "client":"IOS",
    "origin": {
      "locationType": "POINT",
      "point": {"lat": 50.105827, "lon": 14.415478}
    },
    "destination": {
      "locationType": "POINT",
      "point": {"lat": 50.090438, "lon": 14.368958}
    },
    "settings": {
      "profile": "CASUAL_CYCLING",
      "factorPreferences": {}
    },
    "key": "<YOUR ROUTING API KEY>"
  },
  "status": "OK",
  "routes":[
    {"id": 0, "start": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182}},
    {"id": 1, "start": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182}}
  ],
  "creationTimestamp": "2019-11-01T16:00:00.000Z"
}

3.4 Route

Specifies one of the suggested routes between locations in the request. A route consists of one or more legs. For routes that contain no waypoints, the route consists of a single leg (see 3.5 Route Leg); for routes that define one or more waypoints, the route consists of multiple legs corresponding to those route segments.

Fields

id:

Route ID unique within the response.

start:

Start location of the route.

end:

End location of the route.

labels:

Set of labels describing route characteristics. A route containing FAST has the lowest travel time found for the given request. A route containing BIKE_FRIENDLY has the highest percentage of bike-friendly segments (see 3.8 Statistics). Other possible values are ALTERNATIVE, CLEANEST_AIR.

stats:

Route statistics. Details in Section 3.8 Statistics.

legs:

List of legs that compose this route. Details in Section 3.5 Route Leg.

boundingBox:

Geographical boundaries (expressed in GPS coordinates) of the route.

geoJson:

Route representation in GeoJSON format. See Section 3.9 Route GeoJSON.

Response JSON snippet showing an example of one route object:

{
  "routes":[
    {
      "id": 0,
      "start": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182},
      "end": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182},
      "labels": ["BIKE_FRIENDLY"],
      "stats": {
        "distanceMeters": 14934,
        "durationSeconds": 5205,
        "userSettingsMatch": 86,
        "elevationGainMeters": 87,
        "elevationDropMeters": 91
      },
      "legs": ["array of route leg objects"],
      "boundingBox": {
        "topLeft": {"lat": 50.109093, "lon": 14.411273},
        "bottomRight": {"lat": 50.109093, "lon": 14.411273}
      },
      "type": "BIKE"
    }
  ]
}

3.5 Route Leg

The Route Leg object specifies a part of a route directly connecting two locations without intermediate waypoints. A leg consists of one or more Route Steps.

Fields

id:

Leg ID unique within the route.

start:

Start location of the leg.

end:

End location of the leg.

stats:

Leg statistics (same as the route stats in Section 3.8 Statistics).

steps:

List of individual steps (details in Section 3.6 Route Step).

Response JSON snippet showing an example leg object:

{
  "legs": [
    {
      "id": 0,
      "start": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182},
      "end": {"lat": 50.086841, "lon": 14.420565, "elevationMeters": 191},
      "stats": {
        "distanceMeters": 4683,
        "durationSeconds": 1311,
        "userSettingsMatch": 86,
        "elevationGainMeters": 40,
        "elevationDropMeters": 39
      },
      "mode": "BIKE",
      "steps":[
        {
          "start": {"lat": 50.107622, "lon": 14.41498, "elevationMeters": 183},
          "end": {"lat": 50.102987, "lon": 14.423236, "elevationMeters": 222},
          "via": [
            {"lat": 50.107651, "lon": 14.415024, "elevationMeters": 183},
            {"lat": 50.107651, "lon": 14.415024, "elevationMeters": 183}
          ],
          "distanceMeters": 1977,
          "durationSeconds": 543,
          "instruction": {
            "manoeuvre": "RIGHT",
            "streetName": "Královská obora",
            "bicycleRouteName": "201, A162"
          }
        }
      ]
    }
  ]
}

3.6 Route Step

A Route Step is the lowest-level atomic part of a route and specifies the route section between successive guidance instructions (for example, turn left).

Fields

start:

Start location of the step.

end:

End location of the step.

via:

Via location objects of the step used to draw it precisely on the map.

distanceMeters:

Distance in meters to the next step.

durationSeconds:

Duration in seconds to the next step.

instruction:

Instruction at the step’s start location for executing this step (details in Section 3.7 Instruction).

3.7 Instruction

The instruction object contains detailed information about the manoeuvre (for example, whether to turn left or right and on which street or way to continue).

manoeuvre:

Possible values grouped by manoeuvre type:

• Basic navigation manoeuvres: Standard turn and movement instructions used on regular segments. LEFT, RIGHT, SLIGHTLY_LEFT, SLIGHTLY_RIGHT, SHARP_LEFT, SHARP_RIGHT, CONTINUE, U_TURN.

• Roundabout exit manoeuvres: Instructions for selecting a specific roundabout exit. TAKE_THE_*_EXIT (for example TAKE_THE_FIRST_EXIT through TAKE_THE_TENTH_EXIT).

• Infrastructure transition manoeuvres: Instructions describing turns with transition to a specific new road infrastructure type. LEFT_TO_SIDEWALK, RIGHT_TO_SIDEWALK, LEFT_TO_CYCLEWAY, RIGHT_TO_CYCLEWAY, LEFT_TO_ROAD, RIGHT_TO_ROAD.

• Road crossing manoeuvres: Instructions defining a road crossing, or a turn followed by a road crossing. CROSS_ROAD, LEFT_AND_CROSS_ROAD, RIGHT_AND_CROSS_ROAD.

• Heading instructions: Used at route start to indicate the initial heading direction. NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST, NORTH, WEST, SOUTH, EAST.

• Special case: WAYPOINT is present at the instruction where a waypoint is placed and reached.

streetName:

Name of the street to which this instruction leads.

bicycleRouteName:

Name of the bicycle route to which this instruction leads.

3.8 Statistics

The statistics object contains information about a given part of a route (for example, a full route or a leg).

Fields

distanceMeters:

Route distance in meters.

durationSeconds:

Route duration in seconds.

userSettingsMatch:

Route Match score (0-100%) for the whole route. This is the route-level match value from the Match model and is exposed in the route stats object (see Section 1.1 Match Model).

physicalEffortKj:

Physical effort in kJ required to ride the route.

elevationGainMeters:

Total elevation gain in meters along the route.

elevationDropMeters:

Total elevation drop in meters along the route.

emissionsGramsCO2:

CO2 emissions in grams that would be emitted if this route were traveled by car.

slopePercent:

The average slope in percent.

steepSlopesPercentage:

Percentage of steep route segments with a slope greater than 6%.

traffic:

Percentage of route segments with high traffic.

smoothness:

Percentage of route segments with poor smoothness.

Note

For recreational cycling use cases, we recommend routes with the highest userSettingsMatch values. Actual values depend heavily on local infrastructure conditions. In some areas, even the most walk/bike-friendly routes may still have a low match score; in other areas, even the fastest direct route may have a high match score.

3.9 Route GeoJSON

The GeoJSON representation of a route is included as one FeatureCollection object containing a list of Feature objects. Each Feature represents a route segment with LineString geometry and the following properties:

distance:

Route segment distance in meters.

stress:

Traffic stress level on the route segment as an integer from 1 to 5, where 1 means the lowest stress and 5 means the highest stress.

slope:

Slope in percent on the route segment. Positive values indicate uphill, negative values indicate downhill.

popularity:

Route segment popularity category as an integer from 0 to 4, where 0 is the lowest category and 4 is the highest category.

surfaceSmoothness:

Category of surface smoothness on the route segment. Possible values: PAVED_EXCELLENT, PAVED_GOOD, PAVED_INTERMEDIATE, PAVED_BAD, UNPAVED_INTERMEDIATE, UNPAVED_BAD, UNPAVED_HORRIBLE, UNPAVED_IMPASSABLE.

water:

Indicates how much the route segment leads along water objects (for example river or lake). Integer from 0 to 10, where 0 means no nearby water objects and 10 means significant nearby water objects.

greenery:

Indicates how much the route segment leads along greenery objects (for example forest or park). Integer from 0 to 10, where 0 means no nearby greenery objects and 10 means significant nearby greenery objects.

airPollutionNo2:

Average NO2 air pollution on the route segment in micrograms per cubic meter. This value is available only in Belgium (data source: Belgian Interregional Environment Agency and Flanders Environment Agency).

settingsMatch:

Boolean true/false value that indicates whether the route segment matches user-defined routing settings (the preferencesMatch is high enough).

preferencesMatch:

Match percentage of the route segment against user-defined routing preferences as an integer from 0 to 100 (see Section 1.1 Match Model).

An example route GeoJSON:

{
  "type":"FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [[9.148466, 48.430829], [9.148745, 48.43099]]
      },
      "properties":{
        "stress": 2,
        "slope": 5.0,
        "distance": 27,
        "popularity": 3,
        "surfaceSmoothness": "PAVED_EXCELLENT",
        "water": 4,
        "greenery": 7,
        "airPollutionNo2": 18.6,
        "settingsMatch": true,
        "preferencesMatch": 86
      }
    }
  ]
}

3.10 Location

The Routing API location object consists of three fields:

lat:

Latitude coordinate.

lon:

Longitude coordinate.

elevationMeters:

Elevation in meters above mean sea level.