Directions API
Route service allows to make the fastest and the most efficient route between two or more locations (up to 50 waypoints). Nevertheless, trip service solves the Traveling Salesman problem, optimizing routes with up to 50 waypoints.
We use the OSRM as the routing engine, however, instead of the OSM data, our own road network - the most comprehensive road network for Latvia - is used. Directions API currently suppports profiles for both pedestrians and drivers of automobiles. You can read the full documentation here.
If you are interested in using other types of OSRM services (table, nearest, match, tile), e-mail us!
API URL
The request URL should match the following pattern:
https://api.kartes.lv/v3//directions/{profile}/{service}/{coordinates}?
The response is given in JSON
The HTTP GET and POST request methods are used.
Route service
The request URL should match the following pattern:
https://api.kartes.lv/v3//directions/{profile}/route/{coordinates}?
Query parameters
The query might consist of the following GET parameters:
| Parameter | Description | Values |
|---|---|---|
| profile | Mode of transportation. For now, there are two profiles. |
|
| coordinates | String of format {longitude},{latitude};{longitude},{latitude} (up to 50 points) or polyline({polyline}) or polyline6({polyline6}) | x1,y1;x2,y2;…;xn,yn, where:
|
| alternatives | Searches for alternative routes. |
|
| geometries | Returned route geometry format. |
|
| steps | Returns route steps for each route leg. |
|
| overview | Adds overview geometry either full, simplified (according to highest zoom level it could be displayed on), or not at all |
|
| summary | Summary of the route taken as a string. Names of the two major roads are used (e.g., "Daugavgrīvas iela, Krišjāņa Valdemāra iela"). | Active if steps=true
|
| annotations | Returns additional metadata (see below) for each coordinate along the route geometry. |
|
| continue_straight | Forces the route to keep going straight at waypoints constraining uturns there even if it would be faster. By default, uturns are constrained. |
|
| skip_waypoints | Skip waypoints information. |
|
| generate_hints | Generate hints (uuid). |
|
| approaches | Will respect the sides of the road at the terminus | Format: terminus 1;terminus 2
|
Response parameters
The response consists of the following parameters and objects:
| Parametrs | Skaidrojums |
|---|---|
| code | Request success. Ok if successful. |
| waypoints | Object used to describe waypoint on a route. |
| hint | uuid. |
| distance | The distance from the given coordinates to the destination coordinates in meters. |
| location | The coordinates of the location (waypoint, intersection, maneuver) that are used instead of the given coordinates. |
| name | Terminus street name (if any). |
| routes | Object used to describe routes. |
| legs | The legs between the given waypoints, an array of RouteLeg objects. The leg or legs are being followed by distance, duration, weight, summary parameters. |
| steps | Object used to describe steps. There are more parameters for leg (look at OSRM API documantation). |
| weight | Weight (for prioritization). |
| distance | Length (meters). |
| summary | Descriptive name (for example, "Daugavgrīvas iela, Krišjāņa Valdemāra iela"). |
| duration | Duration (sec). |
| weight_name | Weight name. |
| geometry | The whole geometry of the route value depending on overview parameter, format depending on the geometries parameter. |
| weight | The calculated weight of the route. |
| distance | Length (meters). |
| duration | Duration (sec). |
Error codes
| Status code | Description |
|---|---|
| 400 | Wrong input data. Server can’t respond due to client error. |
| 404 | No location found. The URL is not recognized; the resource does not exist. |
| 5xx | Server error. |
Examples
Input:
https://api.kartes.lv/v3//directions/driving/route/24.106237,56.964682;24.094009,56.960553?overview=full&annotations=true&steps=true
Response:
{
"code": "Ok",
"waypoints": [
{
"hint": "aC0AgP___38DAAAAJwAAAAAAAAAAAAAAupanQDs9YEIAAAAAAAAAAAMAAAAsAAAAAAAAAAAAAAAgAAAA39RvAUs2ZQP91G8BSjZlAwAAbwsqWsg3",
"distance": 1.827851,
"location": [
24.106207,
56.964683
],
"name": "Pulkveža Brieža iela"
},
{
"hint": "Wm8KgHNvCoAAAAAACQAAABwCAAB-AQAAAAAAAJEqrUA5zG1Dpi5fQwAAAAAKAAAANwIAAJEBAAAgAAAAIqlvAbwhZQM5pW8BKSZlAwIAfw4qWsg3",
"distance": 140.090272,
"location": [
24.09501,
56.95942
],
"name": ""
}
],
"routes": [
{
"legs": [
{
"steps": [
{
"intersections": [
{
"out": 0,
"entry": [
true
],
"location": [
24.106207,
56.964683
],
"bearings": [
182
]
},
{
"out": 1,
"in": 0,
"entry": [
false,
true,
true
],
"location": [
24.10617,
56.96418
],
"bearings": [
0,
180,
270
]
}
],
"driving_side": "right",
"maneuver": {
"bearing_after": 182,
"bearing_before": 0,
"type": "depart",
"location": [
24.106207,
56.964683
]
},
"duration": 29.3,
"distance": 220.1,
"name": "Pulkveža Brieža iela",
"geometry": "g|tzIyfcrCbBFpBF|@BlAPf@H",
"ref": "P1",
"weight": 26.1,
"mode": "driving"
},...
],
"weight": 208.1,
"distance": 1629.3,
"annotation": {
"speed": [
13.7,
13.8,
...
],
"metadata": {
"datasource_names": [
"lua profile"
]
},
"nodes": [
4777473,
3090436,
...
],
"duration": [
4.1,
4.6,
...
],
"distance": [
55.991795,
63.44537,
...
],
"weight": [
3.6,
4.1,
...
],
"datasources": [
0,
0,
...
]
},
"summary": "Hanzas iela, Eksporta iela",
"duration": 220
}
],
"weight_name": "routability",
"geometry": "g|tzIyfcrCbBFpBF|@BlAPf@HBp@@F?FAx@G|BKpF@R?TNfEHfCDfANpD@Z@ZD|B@NDhD@`@fA@JAvH?hBB`AA\\DXRVLPBt@A`BC`@Ab@B\\HvAz@bAj@NJG`AADALCLGXQd@_@t@_@`@uJfGEM",
"weight": 208.1,
"distance": 1629.3,
"duration": 220
}
]
}
Trip service
The trip service solves the Traveling Salesman Problem, providing the most efficient route and order between up to 50 points. Note that all input coordinates have to be connected for the trip service to work. The trip service is enabled by using the trip value (instead of route) as the service parameter.
Additional query parameters
| Parameter | Description | Possible values |
|---|---|---|
| roundtrip | Returned route is a roundtrip (route returns to the first location). |
|
| source | Returned route starts at any or first coordinate. |
|
| destination | Returned route ends at any or last coordinate. |
|
If source=any&destination=any, the returned roundtrip will still start at the first input coordinate by default.
Additional response parameters
| Parameter | Description |
|---|---|
| code | If the request was successful, Ok. |
| waypoints | Array of Waypoint objects representing all waypoints in input order. |
| trip_index | Index to trips of the sub-trip the point was matched to. |
| waypoint_index | Index of the point in the trip. |
| trips | An array of Route objects that assemble the trace. |
Examples
Input:
https://api.kartes.lv/v3//directions/driving/trip/24.12,56.92;24.13,56.95;24.11,56.91;24.16,56.98?overview=full&annotations=true&steps=true&geometries=geojson&source=first&destination=last
Response:
{
"code": "Ok",
"waypoints": [
{
"waypoint_index": 0,
"trips_index": 0,
"hint": "Ev8JgE3_CYAiAAAAGQAAAF8AAADFAAAAmvGaQZ47V0EvUFNCIdLbQiIAAAAZAAAAXwAAAMUAAAAgAAAAoQtwAfGIZAPACnABwIdkAwMAPxIqWsg3",
"distance": 36.624429,
"location": [
24.120225,
56.920305
],
"name": ""
},
{
"waypoint_index": 2,
"trips_index": 0,
"hint": "ym0KgDVuCoBLAAAAAAAAAAAAAAA9AAAAVEIuQgAAAAAAAAAANckPQk4AAAAAAAAAAAAAAEAAAAAgAAAANDJwAcj8ZAPQMXAB8PxkAwAArxUqWsg3",
"distance": 7.544916,
"location": [
24.1301,
56.94996
],
"name": ""
},
{
"waypoint_index": 1,
"trips_index": 0,
"hint": "iB4BgKgeAYAeAAAAAAAAAPsAAAAFAAAA4KXHQQAAAAAhDlJDgfyMQB4AAAAAAAAA-wAAAAUAAAAgAAAAAuJvAQRiZAOw428BsGBkAw4Afw4qWsg3",
"distance": 46.035301,
"location": [
24.10957,
56.91034
],
"name": "Tumes iela"
},
{
"waypoint_index": 3,
"trips_index": 0,
"hint": "3WQKgPNkCoANAAAABwAAAGEBAAC0AAAAzD8DQab_YEAlWk5DVMvSQg4AAAAHAAAAcQEAAL4AAAAgAAAA_qZwASByZQMAp3ABIHJlAwgAXxUqWsg3",
"distance": 0.12163,
"location": [
24.159998,
56.98
],
"name": ""
}
],
"trips": [
{
"legs": [
{
"steps": [
{
"intersections": [
{
"classes": [
"unpaved"
],
"out": 0,
"entry": [
true
],
"location": [
24.120225,
56.920305
],
"bearings": [
292
]
},...
],
"driving_side": "right",
"geometry": {
"coordinates": [
[
24.120225,
56.920305
],...
],
"type": "LineString"
},
"duration": 138.3,
"distance": 737.7,
"name": "",
"weight": 138.3,
"mode": "driving",
"maneuver": {
"bearing_after": 292,
"location": [
24.120225,
56.920305
],
"type": "depart",
"bearing_before": 0,
"modifier": "left"
},
},...
],
"weight": 434.5,
"distance": 3852.5,
"annotation": {
"speed": [
5.4,
5.6,
...
],
"metadata": {
"datasource_names": [
"lua profile"
]
},
"nodes": [
4539416,
5195632,
...
],
"duration": [
2.5,
19.7,
...
],
"distance": [
13.413894,
109.603385,
...
],
"weight": [
2.5,
19.7,
...
],
"datasources": [
0,
0,
...
]
},
"summary": "Mūkusalas iela, Tumes iela",
"duration": 465.8,
},...
],
"weight_name": "routability",
"geometry": {
"coordinates": [
[
24.120225,
56.920305
],
...
[
24.120225,
56.920305
]
],
"type": "LineString"
},
"weight": 2680.1,
"distance": 26133.8,
"duration": 2885.3
}
]
}