v1

latestOpenAPI 3.0.1CC-BY 4.0 license2026-07-171752.0 KB

Routes

compute a route

This creates a new route. The payload of the request specifies the definition of the new route.

At a minimum, a route is defined by two waypoints, the start and end point of the route.

Every API has to support at least 'fastest' and 'shortest' as the routing preference. The default value is 'fastest'.

An optional name for the route may be provided. The name will be used as the title in links to the route (e.g., in the response to /routes) and also included in the route itself.

More parameters and routing constraints can optionally be provided with the routing request:

Source dataset to use when processing the route
Routing engine to use when processing the route
Routing algorithm to use when processing the route
Obstacle requirements
Height restriction
Maximum load restriction
Time of departure or arrival

If the parameter mode is not provided or has a value 'async' the response returns a link the new route in the Location header. If the value is 'sync' no route resource is created on the server, but the connection is kept open until the route has been computed. The response contains the route. In synchronous mode the subscriber property is ignored.

post/routes

Query parameters

mode'async' | 'sync'

Example:sync

Controls whether the request is processed asynchronuous (the default) or synchronous (the route isreturned in the response to the POST request and not stored on the routing server).

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'sync-mode' is not listed in the conformance declaration under /conformance.

Request body

namestring

An optional name for the route. If provided, the name will be used as titles in the list of routes (/routes) and also included in the route itself.

preference'fastest' | 'shortest'

The routing preference.

Every API has to support at least 'fastest' and 'shortest'. The default value should be 'fastest'.

maxHeightnumber

A height restriction for vehicles in meters to consider when computing the route.

If a server does not have sufficient data to compute a route with height restrictions for the selected area or the selected routing engine does not support such restrictions, an error is returned (status code 400).

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'max-height' is not listed in the conformance declaration under /conformance.

maxWeightnumber

A weight restriction for vehicles in tons to consider when computing the route.

If a server does not have sufficient data to compute a route with weight restrictions for the selected area or the selected routing engine does not support such restrictions, an error is returned (status code 400).

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'max-weight' is not listed in the conformance declaration under /conformance.

dataset'NSG' | 'OSM' | 'HERE'

The source dataset to use for calculating the route.

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'source-dataset' is not listed in the conformance declaration under /conformance. The enum values may be changed to reflect the datasets supported by the server.

engine'Skymantics' | 'Ecere' | 'HERE'

The routing engine to use for calculating the route.

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'routing-engine' is not listed in the conformance declaration under /conformance. The enum values may be changed to reflect the routing engines supported by the server.

algorithm'Dikjstra' | 'Floyd Marshall' | 'A*'

The routing / graph solving algorithm to use for calculating the route.

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'routing-algorithm' is not listed in the conformance declaration under /conformance. The enum values may be changed to reflect the routing algorithms supported by the server.

subscriberstring uri

Optional URI for a callback once the route has been calculated.

Support for this parameter is not required and the parameter may be removed from the API definition, if conformance class 'callback' is not listed in the conformance declaration under /conformance.

Example request

{
  "name": "Route from A to B",
  "waypoints": {
    "type": "MultiPoint",
    "coordinates": [
      [
        36.1234515,
        32.6453783
      ],
      [
        36.1214698,
        32.655952
      ],
      [
        36.1247213,
        32.7106286
      ]
    ]
  },
  "preference": "fastest",
  "maxHeight": 4.5,
  "maxWeight": 12,
  "obstacles": {
    "type": "MultiPolygon",
    "coordinates": [
      [
        [
          [
            8.711910494386,
            51.491083768767
          ],
          [
            8.712299962793,
            51.491067136843
          ],
          [
            8.712384807593,
            51.491645254752
          ],
          [
            8.712013831642,
            51.491666041604
          ],
          [
            8.711993473545,
            51.491602869418
          ],
          [
            8.711960339932,
            51.49139558179
          ],
          [
            8.711953300233,
            51.491351549805
          ],
          [
            8.711910494386,
            51.491083768767
          ]
        ]
      ],
      [
        [
          [
            8.697513007025,
            51.501441332828
          ],
          [
            8.697820179888,
            51.501288905065
          ],
          [
            8.699285444474,
            51.502523857373
          ],
          [
            8.698973376983,
            51.502594262617
          ],
          [
            8.6989379014,
            51.502640856746
          ],
          [
            8.698295428102,
            51.502100015612
          ],
          [
            8.697513007025,
            51.501441332828
          ]
        ]
      ]
    ]
  },
  "dataset": "OSM",
  "engine": "Skymantics",
  "algorithm": "Dikjstra",
  "when": {
    "timestamp": "2019-05-23T19:06:32Z",
    "type": "arrival"
  },
  "subscriber": "https://client.example.com/notification/36d49f"
}

Response

This response is only returned for synchronous processing (mode=sync). The response is the route.

If the request included an Accept-Language, the server will try to honor the request and otherwise fall back to an available language.

All 1 operations