Directions API

Route service allows to make the fastest and the most efficient route between two or more locations (up to 50 waypoints). Meawwhile, 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 . For now, our Directions API support profiles for car drivers and pedestrians. You can read 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.

  • client_key: Your authorisation key.

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.
  • driving - car (default value)
  • walking - pedestrian
service Type of service.
  • route - for finding the fastest way between two or more waypoints
  • trip - for solving the travelling salesman problem and finding the best order of the multiple waypoints
coordinates String of format {longitude},{latitude};{longitude},{latitude} or polyline({polyline}) or polyline6({polyline6}) x1,y1;x2,y2;…;xn,yn, where:
  • x1 - the x-coordinate of the starting point.
  • y1 - the y-coordinate of the starting point;
  • x2 - the x-coordinate of the next waypoint;
  • y2 - the y-coordinate of the next waypoint;
  • xn - the x-coordinate of the last waypoint;
  • yn - the y-coordinate of the last waypoint.
alternatives Searches for alternative routes.
  • true - gives a single alternative route;
  • false - no alternatives (default value);
  • integer - number of alternative routes.
geometries Returned route geometry format.
  • polyline (default value)
  • polyline6
  • geojson
steps Returns route steps for each route leg.
  • false (default value)
  • false
overview Adds overview geometry either full, simplified (according to highest zoom level it could be displayed on), or not at all
  • simplified - simplified geometry (default value))
  • full - detailed geometry
  • false - none
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").
  • true - returns names of the major roads (if the route is too short, gives empty result)
  • false
annotations Returns additional metadata (see below) for each coordinate along the route geometry.
  • true;
  • false (default value).
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.
  • true - continues straight at a waypoint;
  • false - can make a uturn if faster.

Response parameters

The response consists of the following parameters and objects:

Parameter Description
geometry The whole geometry of the route value depending on overview parameter, format depending on the geometries parameter.
steps Route steps for each route leg.
distance The distance traveled by the route, in float meters.
duration The estimated travel time, in float number of seconds.
weight The calculated weight of the route.
weight_name The name of the weight profile used during extraction phase.
summary Summary of the route taken as string. Depends on the summary parameter.
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.
waypoints Object used to describe waypoint on a route. Consists of name, hint, location, distance (here - the distance from the input coordinates to the waypoint coordinate) parameters.
hint 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.
location Array that contains the pair of the snapped coordinate (on the road network).
name Name of the street the coordinate snapped to (if exists).

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",
  "routes": [
    {
      "geometry": "g|tzIyfcrCbBFpBF|@BlAPf@HBp@@F?FAx@G|BKpF@R?TNfEHfCDfANpD@ZBh@BnB@NFzD?NfA@JAvH?hBB`AA\\DXRVLPBt@A`BC`@Ab@B\\HvAz@bAj@NJG`AADALCLGXQd@_@t@_@`@uJfGEM",
      "legs": [
        {
          "annotation": {
            "metadata": {
              "datasource_names": [
                "lua profile"
              ]
            },
            "nodes": [
              2049918,
              ...
              2048950
            ],
            "datasources": [
              0,
              ...
              0
            ],
            "speed": [
              13.7,
              ...
              5.4
            ],
            "weight": [
              3.6,
              ...
              0.9
            ],
            "duration": [
              4.1,
              ...
              1
            ],
            "distance": [
              55.991795,
              ...
              5.399539
            ]
          },
          "steps": [
            {
              "intersections": [
                {
                  "out": 0,
                  "entry": [
                    true
                  ],
                  "bearings": [
                    182
                  ],
                  "location": [
                    24.106207,
                    56.964683
                  ]
                },
                {
                  "out": 1,
                  "location": [
                    24.10617,
                    56.96418
                  ],
                  "bearings": [
                    0,
                    180,
                    270
                  ],
                  "entry": [
                    false,
                    true,
                    true
                  ],
                  "in": 0
                }
              ],
              "driving_side": "right",
              "geometry": "g|tzIyfcrCbBFpBF|@BlAPf@H",
              "mode": "driving",
              "duration": 16.7,
              "maneuver": {
                "bearing_after": 182,
                "location": [
                  24.106207,
                  56.964683
                ],
                "bearing_before": 0,
                "type": "depart"
              },
              "ref": "P1",
              "weight": 14.9,
              "distance": 220.1,
              "name": "Pulkveža Brieža iela"
            }
            ...
            {
              "intersections": [
                {
                  "in": 0,
                  "entry": [
                    true
                  ],
                  "bearings": [
                    232
                  ],
                  "location": [
                    24.09501,
                    56.95942
                  ]
                }
              ],
              "driving_side": "right",
              "geometry": "k{szIy`arC",
              "mode": "driving",
              "duration": 0,
              "maneuver": {
                "bearing_after": 0,
                "type": "arrive",
                "modifier": "left",
                "bearing_before": 52,
                "location": [
                  24.09501,
                  56.95942
                ]
              },
              "weight": 0,
              "distance": 0,
              "name": " "
            }
          ],
          "distance": 1629.4,
          "duration": 157.8,
          "summary": "Eksporta iela,  ",
          "weight": 149.7
        }
      ],
      "distance": 1629.4,
      "duration": 157.8,
      "weight_name": "routability",
      "weight": 149.7
    }
  ],
  "waypoints": [
    {
      "hint": "D1wBgP___38DAAAAJwAAAAAAAAAAAAAAupanQDs9YEIAAAAAAAAAAAMAAAAsAAAAAAAAAAAAAAAaAAAA39RvAUs2ZQP91G8BSjZlAwAAbwttuz33",
      "distance": 1.827851,
      "name": "Pulkveža Brieža iela",
      "location": [
        24.106207,
        56.964683
      ]
    },
    {
      "hint": "BXoMgAd6DIAAAAAACQAAAJgBAAB-AQAAAAAAAJEqrUA5zG1Dpi5fQwAAAAAKAAAAqwEAAJEBAAAaAAAAIqlvAbwhZQM5pW8BKSZlAwIAfw5tuz33",
      "distance": 140.090272,
      "name": " ",
      "location": [
        24.09501,
        56.95942
      ]
    }
  ]
}

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 first location).
  • true - returns (default value). The first location is repeated in the response.
  • false - doesn't return
source Returned route starts at any or first coordinate.
  • any - can start at any of the given coordinates (default value)
  • first - starts at the first coordinates
destination Returned route ends at any or last coordinate.
  • any - can end at any of the given coordinates (default value);
  • last - ends at the last waypoint.

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",
  "trips": [
    {
      "geometry": {
        "coordinates": [
          [
            24.120225,
            56.920305
          ],
          ...
          [
            24.120225,
            56.920305
          ]
        ],
        "type": "LineString"
      },
      "legs": [
        {
          "annotation": {
            "metadata": {
              "datasource_names": [
                "lua profile"
              ]
            },
            "nodes": [
              2041236,
              ...
              2040145
            ],
            "datasources": [
              0,
              ...
              0
            ],
            "speed": [
              5.6,
              ...
              8.3
            ],
            "weight": [
              2.4,
              ...
              3
            ],
            "duration": [
              2.4,
              ...
              3
            ],
            "distance": [
              13.413894,
              ...
              24.901147
            ]
          },
          "steps": [
            {
              "intersections": [
                {
                  "out": 0,
                  "entry": [
                    true
                  ],
                  "bearings": [
                    292
                  ],
                  "location": [
                    24.120225,
                    56.920305
                  ]
                },
                {
                  "out": 2,
                  "location": [
                    24.11837,
                    56.92075
                  ],
                  "bearings": [
                    75,
                    120,
                    300
                  ],
                  "entry": [
                    true,
                    false,
                    true,
                    true
                  ],
                  "in": 1
                },
                {
                  "out": 3,
                  "location": [
                    24.11311,
                    56.92362
                  ],
                  "bearings": [
                    60,
                    150,
                    330
                  ],
                  "entry": [
                    true,
                    false,
                    true
                  ],
                  "in": 1
                }
              ],
              "driving_side": "right",
              "geometry": {
                "coordinates": [
                  [
                    24.120225,
                    56.920305
                  ]
                  ...
                  [
                    24.11164,
                    56.92479
                  ]
                ],
                "type": "LineString"
              },
              "mode": "driving",
              "duration": 138.2,
              "maneuver": {
                "bearing_after": 292,
                "type": "depart",
                "modifier": "left",
                "bearing_before": 0,
                "location": [
                  24.120225,
                  56.920305
                ]
              },
              "weight": 138.2,
              "distance": 737.7,
              "name": " "
            },
            ...
          ],
          "distance": 3466.5,
          "duration": 396.3,
          "summary": " , Putnu iela",
          "weight": 380
        },
        ...
      ],
      "distance": 25447.2,
      "duration": 2288.6,
      "weight_name": "routability",
      "weight": 2147.1
    }
  ],
  "waypoints": [
    {
      "waypoint_index": 0,
      "trips_index": 0,
      "location": [
        24.120225,
        56.920305
      ],
      "name": " ",
      "distance": 36.624429,
      "hint": "8YIPgAGDD4AYAAAAIwAAAMUAAABfAAAAnjtXQZrxmkEh0ttCL1BTQhgAAAAjAAAAxQAAAF8AAAAaAAAAoQtwAfGIZAPACnABwIdkAwEA_wZtuz33"
    },
    {
      "waypoint_index": 2,
      "trips_index": 0,
      "location": [
        24.1301,
        56.94996
      ],
      "name": " ",
      "distance": 7.544916,
      "hint": "dnIMgH1yDIBLAAAAAAAAAAAAAAA9AAAAVEIuQgAAAAAAAAAANckPQk4AAAAAAAAAAAAAAEAAAAAaAAAANDJwAcj8ZAPQMXAB8PxkAwAArxVtuz33"
    },
    {
      "waypoint_index": 1,
      "trips_index": 0,
      "location": [
        24.10957,
        56.91034
      ],
      "name": "Tumes iela",
      "distance": 46.035301,
      "hint": "H6MBgAGkAYAAAAAAHgAAADMAAAD7AAAAAAAAAOClx0FF_LFBIQ5SQwAAAAAeAAAAMwAAAPsAAAAaAAAAAuJvAQRiZAOw428BsGBkAwQAPwNtuz33"
    },
    {
      "waypoint_index": 3,
      "trips_index": 0,
      "location": [
        24.160294,
        56.979942
      ],
      "name": "Augstrozes iela",
      "distance": 19.010534,
      "hint": "hGcMgIxnDIACAAAALwAAAA4AAAAuAAAAs_4lQPa5PEIbJGRBe2U6QgIAAAAxAAAADwAAAC8AAAAaAAAAJqhwAeZxZQMAp3ABIHJlAwEAPwFtuz33"
    }
  ]
}