Routing and Travelling Salesman Problem

Routing API is a service for finding the shortest or the fastest route between two or more geographical points. It can also calculate optimal point sequence (Travelling Salesman Problem - TSP) for up to 100 points, rearranging all the waypoints between start and end to the most optimal order.

GeoDataHub Routing API is based on OSRM Routing Engine. The area of Latvia and Lithuania is covered by Jāņa sēta data, the area of Estonia is covered by © OpenStreetMap contributors data.

Process

Name	Type	Explanation
Is the request valid?	Gateway	The application verifies request parameters.
Error response	Message End	The application creates error response according to "Verification" chapter.
Make routing request	Action	API executes routing according to the request parameters.
Response message	Message End	The application creates response message according to "Response message" chapter.

General request parameters

Request consists of the following URI parameters:

Parameter	Possible values	Default value	Required	Description
`service`	`route`, `trip`	-	Yes	Defines, which type of routing service will be used.
`version`	`v1`	`v1`	Yes	Version of the protocol implemented by the service.
`profile`	`driving`	`driving`	Yes	Mode of transportation. Only 'driving' is available at the moment.
`coordinates`	string	-	Yes	String of coordinates {longitude},{latitude};{longitude},{latitude}
`apikey`	string	-	Yes	Your authorization key.
`format`	`json`	`json`	No	The format in which output is generated.

Route service request parameters

Route service finds the fastest route between coordinates in the supplied order.

The following parameter options are available when route is set for service parameter (see chapter "General request parameters").

Parameter	Possible values	Default value	Required	Description
alternatives	true, false, Number	false	No	Search for alternative routes. Passing a number `alternatives=n` searches for up to n alternative routes.
steps	true, false	false	No	Returned route steps for each route leg.
annotations	true, false, nodes, distance, duration, datasources, weight, speed	false	No	Returns additional metadata for each coordinate along the route geometry.
geometries	polyline, polyline6, geojson	polyline	No	Returned route geometry format (influences overview and per step).
overview	simplified, full, false	simplified	No	Add overview geometry either full or simplified. According to the highest zoom level it could be displayed on, or not at all.
continue_straight	default, true, false	default	No	Forces the route to keep going straight at waypoints constraining u-turns there even if it would be faster. Default value depends on the profile.

Trip service request parameters

The trip service solves the Traveling Salesman Problem (TSP) using a greedy heuristic (farthest-insertion algorithm) for 10 or more waypoints and uses brute force for less than 10 waypoints. The returned path does not have to be the fastest path. As TSP is NP-hard it only returns an approximation. All input coordinates have to be connected for the trip service to work.

The following parameter options are available when trip is set for service parameter (see chapter "General request parameters").

Parameter	Possible values	Default value	Required	Description
roundtrip	true, false	true	No	Returned route is a roundtrip (route returns to first location)
source	any, first	any	No	Returned route starts at any or first coordinate
destination	any, last	any	No	Returned route ends at any or last coordinate
steps	true, false	false	No	Returned route instructions for each trip
annotations	true, false, nodes, distance, duration , datasources, weight, speed	false	No	Returns additional metadata for each coordinate along the route geometry
geometries	polyline, polyline6, geojson	polyline	No	Returned route geometry format (influences overview and per step)
overview	simplified, full, false	simplified	No	Add overview geometry either full, simplified according to highest zoom level it could be displayed on, or not at all

Request URL example

https://api.geodatahub.eu/routing/route/v1/driving/25.140838623046875,57.1801804343149;24.90325927734375,57.08403805143005?apikey=[YOUR_API_KEY]

Verification

Verification	errorCode	errorName	errorDescription
Is API key correct in request?	401	Unauthorized	Invalid authentication credentials
Is API key in request?	400	Bad Request	No API key found in request
Is API key active?	403	Forbidden	Inactive API key found in request
Are 'lat' and 'lon' present in request?	400	Bad request	No 'lat' and 'lon' present in request.
Are 'lat' and 'lon' correct in request?	400	Bad request	Invalid 'lat' and 'lon' coordinates in request
Is parameter 'alternatives' value defined correctly in route service request?	400	Bad request	Incorrectly defined 'alternatives' parameter
Is parameter 'steps' value defined correctly in request?	400	Bad request	Incorrectly defined 'steps' parameter
Is parameter 'annotations' value defined correctly in request?	400	Bad request	Incorrectly defined 'annotations' parameter
Is parameter 'geometries' value defined correctly in request?	400	Bad request	Incorrectly defined 'geometries' parameter
Is parameter 'overview' value defined correctly in request?	400	Bad request	Incorrectly defined 'overview' parameter
Is parameter 'continue _ straight' value defined correctly in route service request?	400	Bad request	Incorrectly defined 'continue _ straight' parameter
Is parameter 'roundtrip' value defined correctly in trip service request?	400	Bad request	Incorrectly defined 'roundtrip' parameter
Is parameter 'source' value defined correctly in trip service request?	400	Bad request	Incorrectly defined 'source' parameter
Is parameter 'destination' value defined correctly in trip service request?	400	Bad request	Incorrectly defined 'destination' parameter

Response parameters

HTTP status = 200;
Body consists of the following values:

Parameter	Type	Presence depends on request parameter?	Description
code	string	No	Status code of the response 'Ok' if successful
routes			An array of Route objects, ordered by descending recommendation rank.
legs			The legs between the given waypoints, an array of RouteLeg objects.
distance	float	No	The distance traveled by this route leg, in meters.
duration	float	No	The estimated travel time, in number of seconds.
weight	float	No	The calculated weight of the route leg.
summary	string	Yes	Summary of the route taken as `string`. Depends on the `summary` parameter:
steps	array	No	Array of `RouteStep` objects describing the turn-by-turn instructions
distance	float	No	The distance of travel from the maneuver to the subsequent step, in meters.
duration	float	No	The estimated travel time, in number of seconds.
geometry	string	Yes	The unsimplified geometry of the route segment, depending on the `geometries` parameter.
weight	float	No	The calculated weight of the step.
mode	string	Yes	A string signifying the mode of transportation.
name	string	No	The name of the way along which travel proceeds.
intersections	array	No	A list of `Intersection` objects that are passed along the segment, the very first belonging to the StepManeuver
location	array	No	A `[longitude, latitude]` pair describing the location of the turn.
bearings	array	No	A list of bearing values (e.g. [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection. Values are between 0-359 (0=true north)
entry	array	No	A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of `true` indicates that the respective road could be entered on a valid route. `false` indicates that the turn onto the respective road would violate a restriction.
in	integer	No	index into bearings/entry array. Used to calculate the bearing just before the turn. Namely, the clockwise angle from true north to the direction of travel immediately before the maneuver/passing the intersection. Bearings are given relative to the intersection. To get the bearing in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for `depart` maneuvers.
out	integer	No	index into the bearings/entry array. Used to extract the bearing just after the turn. Namely, The clockwise angle from true north to the direction of travel immediately after the maneuver/passing the intersection. The value is not supplied for `arrive` maneuvers.
lanes	array	No	Array of `Lane` objects that denote the available turn lanes at the intersection. If no lane information is available for an intersection, the `lanes` property will not be present.

maneuver	object	No	A `StepManeuver` object representing the maneuver.
location	array	No	A `[longitude, latitude]` pair describing the location of the turn.
bearing_after	integer	No	The clockwise angle from true north to the direction of travel immediately after the maneuver. Range 0-359.
bearing_before	integer	No	The clockwise angle from true north to the direction of travel immediately before the maneuver. Range 0-359.
modifier	string	No	An optional `string` indicating the direction change of the maneuver.
type	string	No	A string indicating the type of maneuver.
distance	float	No	The distance traveled by the route, in meters.
duration	float	No	The estimated travel time, in number of seconds.
weight_name	string	No	The name of the weight profile used during extraction phase.
weight	float	No	The calculated weight of the route.
postal_code	string	No	Postal code

waypoints			Array of Waypoint objects representing all waypoints in order
hint	string	No	Unique internal identifier of the segment (ephemeral, not constant over data updates) This can be used on subsequent request to significantly speed up the query and to connect multiple services. E.g. you can use the `hint`value obtained by the `nearest` query as `hint` values for `route` inputs
name	string	No	Name of the street the coordinate snapped to
location	array	No	Array that contains the [longitude, latitude] pair of the snapped coordinate

StepManeuver type property values

type	Description
turn	a basic turn into direction of the `modifier`
new name	no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`
depart	indicates the departure of the leg
arrive	indicates the destination of the leg
merge	merge onto a street (e.g. getting on the highway from a ramp, the `modifier` specifies the direction of the merge)
ramp	Deprecated. Replaced by `on_ramp` and `off_ramp`
on ramp	take a ramp to enter a highway (direction given my `modifier`
off ramp	take a ramp to exit a highway (direction given my `modifier`)
fork	take the left/right side at a fork depending on `modifier`
end of road	road ends in a T intersection turn in direction of `modifier`
use lane	Deprecated. replaced by lanes on all intersection entries
continue	Turn in direction of `modifier` to stay on the same road
roundabout	traverse roundabout, if the route leaves the roundabout there will be an additional property `exit`for exit counting. The modifier specifies the direction of entering the roundabout.
rotary	a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object).
roundabout turn	Describes a turn at a small roundabout that should be treated as normal turn. The `modifier`indicates the turn direciton. Example instruction: `At the roundabout turn left`.
notification	not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction.
exit roundabout	Describes a maneuver exiting a roundabout (usually preceeded by a `roundabout` instruction)
exit rotary	Describes the maneuver exiting a rotary (large named roundabout)

StepManeuver modifier values

modifier	Description
uturn	indicates reversal of direction
sharp right	a sharp right turn
right	a normal turn to the right
slight right	a slight turn to the right
straight	no relevant change in direction
slight left	a slight turn to the left
left	a normal turn to the left
sharp left	a sharp turn to the left

Response examples

{
  "code": "Ok",
  "routes": [
    {
      "geometry": {
        "coordinates": [
          [
            24.183958,
            56.407945
          ],
          [
            24.184005,
            56.407963
          ],
          [
            24.183467,
            56.408449
          ],
          [
            24.183375,
            56.408417
          ],
          [
            24.183071,
            56.408295
          ]
        ],
        "type": "LineString"
      },
      "legs": [
        {
          "annotation": {
            "speed": [
              5.9,
              8,
              8.4,
              8
            ]
          },
          "steps": [],
          "distance": 96.7,
          "duration": 22.8,
          "summary": "",
          "weight": 22.8
        }
      ],
      "distance": 96.7,
      "duration": 22.8,
      "weight_name": "routability",
      "weight": 22.8
    }
  ],
  "waypoints": [
    {
      "hint": "Bz8UgB0_FIBXAAAABgAAAAQBAAAAAAAAmr5zQpihYUBD0jRDAAAAAFcAAAAGAAAABAEAAAAAAAAKAAAAlgRxAYm3XAOEBHEBmLdcAwYAfwNWDL0L",
      "name": "Kalēju iela",
      "location": [
        24.183958,
        56.407945
      ]
    },
    {
      "hint": "GD8UgP___38dAAAAIwAAAAgAAABfAAAAH0u5QYdol0AcfdZAaiCLQh0AAAAjAAAACAAAAF8AAAAKAAAAHwFxAee4XANUAXEBv7hcAwEArw5WDL0L",
      "name": "Rūpniecības iela",
      "location": [
        24.183071,
        56.408295
      ]
    }
  ]
}

{
"code": "Ok",
"trips": [
{
"geometry": "udhwIwlrrCAIaBjB\\nA`AvC~@xDu@t@t@u@Z`A\\r@j@x@JyA?i@Ao@SeBq@wCeBaG",
"legs": [
{
"steps": [],
"distance": 96.7,
"duration": 22.8,
"summary": "",
"weight": 22.8
},
{
"steps": [],
"distance": 161,
"duration": 23.1,
"summary": "",
"weight": 23.1
},
{
"steps": [],
"distance": 355.2,
"duration": 57.9,
"summary": "",
"weight": 57.9
}
],
"distance": 612.9,
"duration": 103.8,
"weight_name": "routability",
"weight": 103.8
}
],
"waypoints": [
{
"waypoint_index": 0,
"location": [
24.183958,
56.407945
],
"name": "Kalēju iela",
"hint": "Bz8UgB0_FIBXAAAABgAAAAQBAAAAAAAAmr5zQpihYUBD0jRDAAAAAFcAAAAGAAAABAEAAAAAAAAKAAAAlgRxAYm3XAOEBHEBmLdcAwYAfwNWDL0L",
"trips_index": 0
},
{
"waypoint_index": 1,
"location": [
24.183071,
56.408295
],
"name": "Rūpniecības iela",
"hint": "GD8UgP___38dAAAAIwAAAAgAAABfAAAAH0u5QYdol0AcfdZAaiCLQh0AAAAjAAAACAAAAF8AAAAKAAAAHwFxAee4XANUAXEBv7hcAwEArw5WDL0L",
"trips_index": 0
},
{
"waypoint_index": 2,
"location": [
24.181108,
56.407919
],
"name": "",
"hint": "CD8UgAs_FIA1AAAAMgAAAAAAAAAAAAAAiqoUQlyaCkIAAAAAAAAAADUAAAAyAAAAAAAAAAAAAAAKAAAAdPlwAW-3XANs-HABHbdcAwAAbwlWDL0L",
"trips_index": 0
}
]
}