Route

Driving routes between points, built by an external routing provider.

A route is a driving path from a start point to an end point, optionally through waypoints, built by an external routing provider rather than by the Navixy platform itself.

route/get uses the account's configured default provider when the request omits provider_type. The three provider-specific pages, Route with Google, Route with OSRM, and Route with Progorod, document the same operation with the provider pinned, and each reports that provider's own failures differently.

Routing is a tariff feature. A request naming a tracker whose plan lacks routing returns error 236.

Route point object

Key point object

API actions

API base path: /route.

Get route

post

/route/get

Return a driving route from start to end, through any waypoints, using a routing provider.

Omit provider_type to use the account's configured default provider. The three provider-specific paths are the same operation with the provider pinned.

Requires the routing tariff feature on every tracker on the account. Without it the call returns error 236.

Authorizations

AuthorizationstringRequired

Either a user session hash or an API key, with the "NVX " prefix, for example "NVX 22eac1c27af4be7b9d04da2ce1af111b". Obtain a session hash from the userAuth operation, or create an API key from the API keys operations. A small number of operations accept a session hash only and reject an API key with error code 4; each says so in its description.

Body

point_limitinteger · min: 2Optional

Optional. Simplify the returned route to at most this many points.

provider_typestring · enumOptional

Optional. Routing provider to use. Omit to use the account's configured default.

Possible values:

minsizenumberOptional

Optional. Default 5. Smoothing threshold in metres. Setting it below the distance between two neighbouring pixels at the current zoom is not recommended.

use_trafficbooleanOptional

Optional. Default false. When false the router runs in optimal mode ignoring traffic; when true it runs in comfort mode using it.

Responses

200

The route

application/json

successbooleanRead-onlyOptional

true if request finished successfully.

Example: true

distanceintegerOptional

Total length in metres.

timeintegerOptional

Total duration in seconds.

400

Bad request. The response body carries the API-level error code in status.code. Validation failures also include an errors array naming each offending parameter.

application/json

402

Error 236: at least one tracker on the account lacks the routing tariff feature.

application/json

403

Error 215: the routing provider returned an error. Error 218: the routing provider rejected the parameters, most often because a point could not be matched to a road or no route exists between them. Both carry an errors array in the response body describing what the provider said.

application/json

default

Error response object

application/json

post/route/get

POST /v2/route/get HTTP/1.1
Host: api.eu.navixy.com
Authorization: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "start": {
    "lat": 1,
    "lng": 1
  },
  "end": {
    "lat": 1,
    "lng": 1
  },
  "waypoints": [
    {
      "lat": 1,
      "lng": 1
    }
  ],
  "point_limit": 1,
  "provider_type": "progorod",
  "minsize": 1,
  "use_traffic": true
}

{
  "success": true,
  "distance": 1,
  "time": 1,
  "list": [
    {
      "lat": 1,
      "lng": 1
    }
  ],
  "key_points": [
    {
      "id": 1,
      "lat": 1,
      "lng": 1,
      "distance": 1,
      "time": 1
    }
  ]
}

Errors

These errors come in addition to the general error codes:

215 - External service error.
218 - Malformed external service parameters.
236 - Feature unavailable due to tariff restrictions, when at least one tracker in the request has no routing tariff feature.

Route point object

Key point object

API actions

Get route

Errors

More in this section

Route with Google

Route with OSRM

Route with Progorod