Optimized Routing

Same request format as Routing, but stop order is determined automatically to minimize total travel time. Supports Time Windows for scheduling stops within specific time ranges.

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

How it works

The first and last locations are treated as fixed origin and destination. All intermediate stops are reordered freely to find the shortest total travel time.

The stop order in the response will differ from the request. Use originalIndex on each waypoint to map results back to your input array.

Request

Identical to POST /directions/v1. See Routing for all parameters.

{
  "profile": "auto",
  "departureTime": "08:00",
  "locations": [
    {
      "latLng": {
        "lat": 56.30294,
        "lng": 22.34013
      }
    },
    {
      "id": "LT000000001",
      "stopDuration": 120,
      "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
  }
}

Response

Same structure as POST /directions/v1. Waypoints are returned in optimized travel order, not input order.

{
  "code": "Ok",
  "waypoints": [
    {
      "id": null,
      "originalIndex": 0,
      "location": {
        "lat": 56.30294,
        "lng": 22.34013
      },
      "arrivalTime": "08:00"
    },
    {
      "id": "LT000000002",
      "originalIndex": 2,
      "location": {
        "lat": 56.309669,
        "lng": 22.339082
      },
      "matchedAddress": "Gamyklos g. 1, LT-89231 Ma\u017eeikiai",
      "relevance": 0.4505,
      "arrivalTime": "08:01"
    },
    {
      "id": "LT000000007",
      "originalIndex": 6,
      "location": {
        "lat": 56.343105,
        "lng": 22.330867
      },
      "matchedAddress": "Tylioji g. 22, LT-89307 Ma\u017eeikiai",
      "relevance": 0.7846,
      "arrivalTime": "08:08"
    },
    {
      "id": "LT000000006",
      "originalIndex": 5,
      "location": {
        "lat": 56.309431,
        "lng": 22.286046
      },
      "matchedAddress": "Tvenkini\u0173 g. 37, LT-89200 Ma\u017eeikiai",
      "relevance": 0.9077,
      "arrivalTime": "08:16"
    },
    {
      "id": "LT000000009",
      "originalIndex": 7,
      "location": {
        "lat": 56.362109,
        "lng": 22.107197
      },
      "matchedAddress": "Vitvari\u0161k\u0117s g. 17, LT-89451 Kugiai",
      "relevance": 0.5558,
      "arrivalTime": "08:41"
    },
    {
      "id": "LT000000003",
      "originalIndex": 3,
      "location": {
        "lat": 55.909723,
        "lng": 21.828937
      },
      "matchedAddress": "V. Ma\u010dernio g. 61, LT-90129 Plung\u0117",
      "relevance": 0.9091,
      "arrivalTime": "09:43"
    },
    {
      "id": "LT000000005",
      "originalIndex": 4,
      "location": {
        "lat": 55.907568,
        "lng": 21.868073
      },
      "matchedAddress": "Tel\u0161i\u0173 g. 90, LT-90164 Plung\u0117",
      "relevance": 0.9091,
      "arrivalTime": "09:48"
    },
    {
      "id": "LT000000001",
      "originalIndex": 1,
      "location": {
        "lat": 55.973316,
        "lng": 22.271395
      },
      "matchedAddress": "Luok\u0117s g. 82, LT-87149 Tel\u0161iai",
      "relevance": 0.8833,
      "arrivalTime": "10:15"
    },
    {
      "id": null,
      "originalIndex": 8,
      "location": {
        "lat": 56.30294,
        "lng": 22.34013
      },
      "arrivalTime": "10:58"
    }
  ],
  "routes": [
    {
      "duration": 10680,
      "distance": 185.88,
      "legs": [
        {
          "duration": 112.097,
          "distance": 0.893,
          "geometry": "wnmkjB..."
        },
        {
          "duration": 424.084,
          "distance": 5.75,
          "geometry": "ojzkjB..."
        },
        {
          "duration": 462.607,
          "distance": 6.834,
          "geometry": "kd|mjB..."
        },
        {
          "duration": 1501.502,
          "distance": 21.938,
          "geometry": "{dzkjBcffo..."
        },
        {
          "duration": 3726.508,
          "distance": 66.034,
          "geometry": "yk`ojB_ah..."
        },
        {
          "duration": 286.13,
          "distance": 3.156,
          "geometry": "ybnsiBil..."
        },
        {
          "duration": 1607.879,
          "distance": 32.922,
          "geometry": "majsiBcf..."
        },
        {
          "duration": 2474.296,
          "distance": 48.349,
          "geometry": "{qjwiBkc..."
        }
      ]
    }
  ]
}

In this example, LT000000002 (originalIndex: 2) was visited before the last stop because that order produces a shorter total route.

Using originalIndex

originalIndex always refers to the position in your original request array. Use it to match response waypoints back to your records:

const waypoints = response.waypoints;

waypoints.forEach((waypoint) => {
  const originalStop = myStops[waypoint.originalIndex];
  console.log(`${originalStop.name} - arrive ${waypoint.arrivalTime}`);
});