Cyclers Navigate Docs

Routing API

1 Introduction

This document describes Cyclers Navigate API (the API further on) for planning of bike journeys provided by Umotional. Cyclers Navigate is the world’s most advanced bicycle route planning engine capable of planning high-quality routes of different types and criteria. Cyclers Navigate API exposes the Cyclers engine’s functionality for integration into partner’s products and services.

The API produces a set of route plans to get from the origin to the destination given specified parameters. For a given request, the API produces a set of three to five route planes (the number can be increased). The proposed routes are calculated so that the individual routes are maximally distinct (i.e. their segments have a small overlap) and that the routes represent different trade-offs between the route’s duration (which is highly correlated with route’s distance/length) and the route’s bike-friendliness, where bike-friendliness itself is calculated based on a multitude of bike-friendliness factors (such as safety, comfort, physical effort and pollution-exposure). The importance of selected bike-friendliness factors can be adjusted using so called routing modifiers (it is e.g. possible to specify that extra effort should be made to avoid high-traffic segments, although this might lead to longer routes compared to when traffic is considered with normal priority).

The API can be accessed through endpoint

POST /v5/routing

HTTPS is preferred over HTTP when calling the API. JSON data format is used for both requests and responses. GZIP is used to minimize the data transfer over the network from the backend to the client.

2 Example Uses

The API can be used to support a number of different routing planning use cases. Below is a description of the most important uses.

2.1 Point-to-Point Routes

Calculating point-to-point routes is the simplest and the default use of the API. It this case, a set of routes that connects a given origin and a given destination is calculated, possibly taking into account routing modifiers.

_images/point_to_point.png

Sample request payload below:

{
  "client":"IOS",
  "origin": { "lat": 50.105827, "lon": 14.415478 },
  "destination": { "lat": 50.090438, "lon": 14.368958 },
  "key":"<YOUR API KEY>"
}

2.2 Point-to-Point Routes with Waypoints

Point-to-point routes can be constrained to pass through specified waypoints. This is achieved by specifying waypoint locations in the waypoints field of the plan request. By default, the route has to pass the waypoints exactly in the order prescribed.

_images/point_to_point_through_waypoints.png

Sample request payload below:

{
  "client":"IOS",
  "origin": { "lat": 50.105827, "lon": 14.415478 },
  "destination": { "lat": 50.090438, "lon": 14.368958 },
  "waypoints": [
    {"lat":50.110808,"lon":14.396338}
  ],
  "key":"<YOUR API KEY>"
}

2.3 Optimized Multi-Stop Routes

The API can also be used to plan routes visiting multiple points of interest in an optimal order.

_images/tour_poi.png

To achieve this, the caller has to specify in the request body:

  • Locations of desired points of interest must be specified in waypoints field.

  • The maximum number of points of interests is 15.

  • Field origin must be equal to destination field.

  • Field optimizeWaypointsOrder must be set to true.

Note

Tour optimization currently only works with predefined point-of-interest locations. The sample below shows currently supported waypoints in Prague. If you want to tour planning on other sets points-of-interests, please send us their locations. In future versions of the API, this limitation will be removed.

Sample request payload below:

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

2.4 Circuit Routes

The API can also be used to plan circuit routes with desired length. To achieve this, the caller has to specify in the request body:

  • Field waypoints must be empty or not specified.

  • Field origin must be equal to destination field.

  • Field desiredLengthMeters in request settings must be set to true.

Sample request payload below:

{
  "client":"IOS",
  "origin": {"lat": 50.105827, "lon": 14.415478 },
  "destination": {"lat": 50.105827, "lon": 14.415478 },
  "settings":{
    "desiredLengthMeters": 5000
  },
  "key":"<YOUR API KEY>"
}

3 Routing API Request

The Routing request should be sent in the body of a POST request to the endpoint specified above.

Routing Request specifies the parameters of the planned journey. Below are pointed out the relevant fields.

Required Parameters

origin

Required origin location expressed as latitude/longitude coordinates, e.g., { "lat": 50.767001, "lon": 15.057661 }.


destination

Required destination location, e.g., { "lat": 50.785911, "lon": 15.063445 }.


client

Client name. Possible values are WEB, ANDROID, IOS.


key

A key which provides access to the API on behalf of a user. Each user of the API has own unique key.

Note

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

Optional Parameters

waypoints

Optional list of waypoints locations, through which the planned routes have to pass, e.g., [{"lat": 50.785911, "lon": 15.063445}, {"lat": 50.767001, "lon": 15.057661}, ...].


settings

Additional routing modifiers, with possible parameters described in section 3.1 Request Settings below.


3.1 Request Settings

Optional Parameters

climbs

Specifies whether special priority should be given to avoiding climbs. Possible values are:

IGNORE = Suggested routes do not consider climbs during route planning

AVOID_IF_REASONABLE = Suggested routes avoid climbs if reasonably possible. Reasonably possible means there exists an alternative route which is not significantly longer or worse in other bike-friendliness factors (default setting).

AVOID_IF_POSSIBLE = Suggested routes avoid climbs if at all possible.


traffic

Specifies whether special priority should be given to avoiding segments with high car traffic. Possible values are:

IGNORE = Suggested routes do not consider car traffic during route planning.

AVOID_IF_REASONABLE = Suggested routes avoid segments with high car traffic if reasonably possible (default).

AVOID_IF_POSSIBLE = Suggested routes avoid high-traffic segments if at all possible.


surface

Specifies how road / cycleway surface smoothness should be handled. Possible values are:

IGNORE = Suggested routes do not consider surface smoothness during route planning.

PREFER_SMOOTH = Suggested routes prefer segments with smoother surface but do not avoid non-smooth segments if these are convenient for other reasons (default).

AVOID_NON_SMOOTH = Suggested routes avoid segments with non-smooth surface if at all possible (the setting suitable for road bikes).


pollution

Specifies how air pollution should be handled. Possible values are:

IGNORE = Suggested routes do not consider pollution during route planning.

AVOID_IF_REASONABLE = Suggested routes avoid segments with high air pollution if reasonably possible (default).

AVOID_IF_POSSIBLE = Suggested routes avoid high pollution segments if at all possible.

Note

Currently available only in Flanders, Belgium


stairs

Specifies how stairs should be handled. Possible values are:

AVOID_IF_POSSIBLE = Suggested routes should avoid staircase segments if possible, i.e., there exist a route avoiding the staircase (default).

STRICTLY_AVOID = Suggested routes must not contain staircase segments.


pavements

Specifies how going through pavements should be handled. Possible values are:

AVOID_IF_POSSIBLE = Suggested routes avoid going on the pavement if at all possible (default).

STRICTLY_AVOID = Suggested routes must not contain pavement segments.


oneways

Specifies how going through one-way streets in the opposite direction should be handled. Possible values are:

AVOID_IF_POSSIBLE = Suggested routes avoid going in the opposite/contra-flow direction if at all possible (default).

STRICTLY_AVOID = Suggested routes must not contain one-way segments through which the user should go in the opposite direction.


optimizeWaypointOrder

Specifies whether the routing engine should optimize the order in which waypoints are visited. Possible values are:

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

Indicates desired route length in meters that should be returned by routing engine.

4 Routing API Response

Routing API returns a Routing Response according to the specified Routing Request.

Routing Response is a wrapper for a planner response to a submitted routing request. Routing Response consists primarily of a set of route plans that have been found by the planner based on the routing request.

Plan specifies one of the suggested ways to move between locations specified in the Request. Plan consists of one or multiple legs. For route plans that contain no waypoints, the plan will consist of a single “leg,” but for plans that define one or more waypoints, the plan will consist of one or more legs, corresponding to the specific legs of the plan.

Required fields

id

The unique id of the routing response.


request

The corresponding routing request.


creationTimestamp

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


status

Routing response status. Possible values are:

OK = Response contains a valid result.

PLAN_NOT_FOUND = No route could be found between the origin and destination given the routing settings.

MAX_WAYPOINTS_EXCEEDED = Too many waypoints were provided in the request.

INVALID_REQUEST = Provided request was invalid. Common causes of this status include an invalid parameter or parameter value.

SERVER_ERROR = Provided request could not be processed due to a server error. The request may succeed if you try again.

LOCATION_NOT_FOUND = Indicates at least one of the locations specified in the request’s origin, destination, or waypoints could not be geocoded.


plans

List of found plans, when status is OK, otherwise will be an empty list. Details describing fields of route plan see in section 4.1 Plan below.

Optional fields

invalidRequest

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


Note

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

Sample of valid response JSON:

{
  "id": "5dbb1131e21b84000723d794",
  "request": {
    "origin": { },
    "destination": { },
    "client": "IOS",
    "key": "<YOUR API KEY>",
    "settings": { }
  },
  "status": "OK",
  "plans":[
    {"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"
}

4.1 Plan

Plan specifies one of the suggested ways to move between locations specified in the Request. Plan consists of one or multiple legs. For route plans that contain no waypoints, the plan will consist of a single “leg,” but for plans that define one or more waypoints, the plan will consist of one or more legs, corresponding to the specific legs of the plan.

Fields

id

Response-unique plan id.


start

Start location of the plan.


end

End location of the plan.


stats

Plan statistics. Details in section 4.5 Statistics below.


legs

List of legs which creates this plan. Details in section 4.2 Leg below.


boundingBox

Represents geographical bounds, in which plan takes place.


Response JSON snippet showing example of plans:

{
  "plans":[
    {
      "id": 0,
      "start": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182},
      "end": {"lat": 50.105819, "lon": 14.415447, "elevationMeters": 182},
      "stats": {"distanceMeters": 14934, "durationSeconds": 5205, "elevationGainMeters": 87, "elevationDropMeters": 91, "bikeConvenience": 115622},
      "legs": [
        { },
        { },
        { }
      ],
      "boundingBox": {"topLeft": {"lat": 50.109093, "lon": 14.411273 }, "bottomRight":{ }},
      "labels": ["BIKE_FRIENDLY"],
      "type": "BIKE"
    },
    { },
    { }
  ]
}

4.2 Leg

Leg specifies the part of the plan directly connecting two locations without intermediate waypoints. Leg consists of one or multiple steps.

Fields

id

Plan-unique leg id.


start

Start location of the leg.


end

End location of the leg.


stats

Leg statistics (same as the plan’s stats in section 4.5 Statistics).


steps

List of individual steps (details in section 4.3 Step below).


Response JSON snippet showing example of leg:

{
  "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, "elevationGainMeters": 40, "elevationDropMeters": 39, "bikeConvenience": 30910},
      "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 }, { }, { }],
          "distanceMeters": 1977,
          "durationSeconds": 543,
          "instruction": {
            "manoeuvre": "RIGHT",
            "streetName": "Královská obora",
            "bicycleRouteName": "201, A162"
          }
        },
        { },
        { }
      ]
    },
    { },
    { }
  ]
}

4.3 Step

Step is the lowest-level atomic part of a plan and specifies the part of the route between successive guidance instructions (e.g., turn left).

Fields

start

Start location of the step.


end

End location of the step.


via

Via locations of the step to draw it precisely in 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 4.4 Instruction below).


4.4 Instruction

manoeuvre

Possible values are LEFT, RIGHT, SLIGHTLY_LEFT, SLIGHTLY_RIGHT, HARD_LEFT, HARD_RIGHT, CONTINUE, U_TURN, ORIGIN, DESTINATION, WAYPOINT.


streetName

Name of the street where to which this instruction is leading.


bicycleRouteName

Name of the bicycle route to which this instruction is leading.


4.5 Statistics

Statistics information about given part of the route plan (e.g. whole plan or leg).

Fields

distanceMeters

Plan distance in meters.


durationSeconds

Plan duration in seconds.


bikeFriendlyRoutesPercentage

Percentage of bike-friendly route segments.


physicalEffortKj

Physical effort in kJ required to ride the route plan.


elevationGainMeters

Elevation gain in meters along the plan.


elevationDropMeters

Elevation drop in meters along the plan.


emissionsGramsCO2

CO2 emissions in grams which would be emitted when cyclist would drive this route plan by a car.


Note

For the tourism use case, we recommend using routes with the highest values of bikeFriendlyRoutesPercentage. How high these percentages are going to be depends largely on local infrastructure conditions, i.e., there could be situations in which even the most bike friendly routes will have a low bikeFriendlyRoutesPercentage score. Equally, there could be situations in which even the most direct, fastest route will have high bikeFriendlyRoutesPercentage.