Routing

Computes a route between two or more locations in the order provided. Accepts up to 150 locations per request.

POST https://dev-api.roadgis.dev/directions/v1
Authorization: Bearer YOUR_API_KEY

Request

{
  "profile": "auto",
  "departureTime": "08:00",
  "stopDuration": 120,
  "locations": [
    {
      "latLng": {
        "lat": 56.30294,
        "lng": 22.34013
      }
    },
    {
      "id": "LT000000001",
      "address_structured": {
        "postcode": "87149",
        "city": "Telšiai",
        "street": "Luokės g. 82"
      }
    },
    {
      "id": "LT000000002",
      "address_structured": {
        "postcode": "89231",
        "city": "Mažeikiai",
        "street": "Gamyklos g.1, Mažeikiai 89231"
      }
    },
    {
      "id": "LT000000003",
      "address_structured": {
        "postcode": "90129",
        "city": "Plungė",
        "street": "V. Mačernio g. 61"
      }
    },
    {
      "id": "LT000000005",
      "address_structured": {
        "postcode": "90164",
        "city": "Plungė",
        "street": "Telšių g. 90"
      }
    },
    {
      "id": "LT000000006",
      "address_structured": {
        "postcode": "89200",
        "city": "Mažeikiai",
        "street": "Tvenkinių g. 37"
      }
    },
    {
      "id": "LT000000007",
      "address_structured": {
        "postcode": "89307",
        "city": "Mazeikiai",
        "street": "tylioji 22"
      }
    },
    {
      "id": "LT000000009",
      "address_structured": {
        "postcode": "89451",
        "city": "Mazeikiu r.",
        "street": "Kugiu km. Vitvariskes g. 17"
      }
    },
    {
      "latLng": {
        "lat": 56.30294,
        "lng": 22.34013
      }
    }
  ],
  "routeModifiers": {
    "excludeUnpaved": false,
    "topSpeed": 80,
    "shortest": false
  },
  "computeOptions": {
    "steps": false
  }
}

Parameters

Field	Type	Required	Description
profile	string	yes	Routing profile: auto, truck, bicycle, pedestrian
locations	array	yes	2–150 locations. See Location Types
departureTime	string	no	Departure time in HH:MM. Enables arrivalTime on each waypoint
stopDuration	integer	no	Seconds spent at each intermediate stop. Default: 0
routeModifiers	object	no	See below
computeOptions	object	no	See below

routeModifiers

Field	Type	Default	Description
excludeUnpaved	boolean	false	Avoid unpaved roads
topSpeed	integer	—	Vehicle top speed in km/h (1–300). Affects travel time estimates
shortest	boolean	false	Prefer shortest distance over fastest time

computeOptions

Field	Type	Default	Description
steps	boolean	false	Include turn-by-turn maneuvers in each leg

Response

{
  "code": "Ok",
  "waypoints": [
    {
      "id": null,
      "originalIndex": 0,
      "location": {
        "lat": 56.30294,
        "lng": 22.34013
      },
      "arrivalTime": "08:00"
    },
    {
      "id": "LT000000001",
      "originalIndex": 1,
      "location": {
        "lat": 55.973316,
        "lng": 22.271395
      },
      "matchedAddress": "Luokės g. 82, LT-87149 Telšiai",
      "relevance": 0.8833,
      "arrivalTime": "08:41"
    },
    {
      "id": "LT000000002",
      "originalIndex": 2,
      "location": {
        "lat": 56.309669,
        "lng": 22.339082
      },
      "matchedAddress": "Gamyklos g. 1, LT-89231 Mažeikiai",
      "relevance": 0.4505,
      "arrivalTime": "09:26"
    },
    {
      "id": "LT000000003",
      "originalIndex": 3,
      "location": {
        "lat": 55.909723,
        "lng": 21.828937
      },
      "matchedAddress": "V. Mačernio g. 61, LT-90129 Plungė",
      "relevance": 0.9091,
      "arrivalTime": "10:18"
    },
    {
      "id": "LT000000005",
      "originalIndex": 4,
      "location": {
        "lat": 55.907568,
        "lng": 21.868073
      },
      "matchedAddress": "Telšių g. 90, LT-90164 Plungė",
      "relevance": 0.9091,
      "arrivalTime": "10:25"
    },
    {
      "id": "LT000000006",
      "originalIndex": 5,
      "location": {
        "lat": 56.309431,
        "lng": 22.286046
      },
      "matchedAddress": "Tvenkinių g. 37, LT-89200 Mažeikiai",
      "relevance": 0.9077,
      "arrivalTime": "11:19"
    },
    {
      "id": "LT000000007",
      "originalIndex": 6,
      "location": {
        "lat": 56.343105,
        "lng": 22.330867
      },
      "matchedAddress": "Tylioji g. 22, LT-89307 Mažeikiai",
      "relevance": 0.7846,
      "arrivalTime": "11:29"
    },
    {
      "id": "LT000000009",
      "originalIndex": 7,
      "location": {
        "lat": 56.362109,
        "lng": 22.107197
      },
      "matchedAddress": "Vitvariškės g. 17, LT-89451 Kugiai",
      "relevance": 0.5558,
      "arrivalTime": "12:00"
    },
    {
      "id": null,
      "originalIndex": 8,
      "location": {
        "lat": 56.30294,
        "lng": 22.34013
      },
      "arrivalTime": "12:29"
    }
  ],
  "routes": [
    {
      "duration": 16163.405,
      "distance": 278.782,
      "legs": [
        {
          "duration": 2496.325,
          "distance": 48.265,
          "geometry": "wnmkjB..."
        },
        {
          "duration": 2549.668,
          "distance": 49.149,
          "geometry": "{qjwiB..."
        },
        {
          "duration": 3033.083,
          "distance": 57.549,
          "geometry": "ojzkjB..."
        },
        {
          "duration": 286.13,
          "distance": 3.156,
          "geometry": "ybnsiB..."
        },
        {
          "duration": 3110.439,
          "distance": 61.426,
          "geometry": "majsiB..."
        },
        {
          "duration": 471.583,
          "distance": 6.906,
          "geometry": "{dzkjBc..."
        },
        {
          "duration": 1742.15,
          "distance": 27.406,
          "geometry": "kd|mjB{..."
        },
        {
          "duration": 1634.023,
          "distance": 24.922,
          "geometry": "yk`ojB_..."
        }
      ]
    }
  ]
}

Waypoint fields

Field	Type	Description
id	string | null	Echoed from the input location
originalIndex	integer	Position in the caller’s input array
location	object	Snapped coordinates { lat, lng }
matchedAddress	string | null	Resolved address. Present for address and address_structured inputs, null for latLng
relevance	number | null	Geocoding confidence score (0–1). Present alongside matchedAddress
arrivalTime	string	Estimated arrival in HH:MM. Present only when departureTime is provided

Route fields

Field	Type	Description
duration	number	Total trip duration in seconds, including stopDuration at each intermediate stop
distance	number	Total trip distance in kilometres
legs	array	One entry per segment between consecutive waypoints

Leg fields

Field	Type	Description
duration	number	Driving time for this leg in seconds. Does not include stopDuration
distance	number	Leg distance in kilometres
geometry	string	Google-encoded polyline
steps	array	Turn-by-turn maneuvers. Present only when computeOptions.steps is true

Excluded waypoints

When one or more addresses cannot be resolved above the confidence threshold, those locations are excluded from routing. The route is still computed for the remaining locations.

Excluded locations are returned in excluded_waypoints:

{
  "code": "Ok",
  "waypoints": [...],
  "routes": [...],
  "excluded_waypoints": [
    {
      "originalIndex": 2,
      "id": "stop-2",
      "input": "Nowhere St. 999, Vilnius",
      "relevance": 0.08
    }
  ]
}

Field	Type	Description
originalIndex	integer	Position in the caller’s input array
id	string | null	Echoed from the input location
input	string	The input address as provided
relevance	number	Best match score found — below the resolution threshold

If fewer than 2 locations remain after exclusions, the request returns 422 with code: GeocodingFailed and the full excluded_waypoints list.

Error codes

Code	HTTP	Description
GeocodingFailed	422	Fewer than 2 locations could be geocoded
NoRoute	422	No route found between the locations
NoSegment	422	A location cannot be snapped to the road network
InvalidInput	400	Missing or invalid request parameters
Unauthorized	401	Missing or invalid API key
Forbidden	403	Account not verified
QuotaExceeded	429	Monthly quota reached
UpstreamError	503	Routing service unavailable