Optimized Routing

Same request format as Routing, but stop order is determined automatically to minimize total travel time.

POST https://dev-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",
  "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
  }
}

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": "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": "LT000000003",
      "originalIndex": 3,
      "location": {
        "lat": 55.909723,
        "lng": 21.828937
      },
      "matchedAddress": "V. Mačernio g. 61, LT-90129 Plungė",
      "relevance": 0.9091,
      "arrivalTime": "09:13"
    },
    {
      "id": "LT000000005",
      "originalIndex": 4,
      "location": {
        "lat": 55.907568,
        "lng": 21.868073
      },
      "matchedAddress": "Telšių g. 90, LT-90164 Plungė",
      "relevance": 0.9091,
      "arrivalTime": "09:20"
    },
    {
      "id": "LT000000009",
      "originalIndex": 7,
      "location": {
        "lat": 56.362109,
        "lng": 22.107197
      },
      "matchedAddress": "Vitvariškės g. 17, LT-89451 Kugiai",
      "relevance": 0.5558,
      "arrivalTime": "10:21"
    },
    {
      "id": "LT000000006",
      "originalIndex": 5,
      "location": {
        "lat": 56.309431,
        "lng": 22.286046
      },
      "matchedAddress": "Tvenkinių g. 37, LT-89200 Mažeikiai",
      "relevance": 0.9077,
      "arrivalTime": "10:48"
    },
    {
      "id": "LT000000007",
      "originalIndex": 6,
      "location": {
        "lat": 56.343105,
        "lng": 22.330867
      },
      "matchedAddress": "Tylioji g. 22, LT-89307 Mažeikiai",
      "relevance": 0.7846,
      "arrivalTime": "10:58"
    },
    {
      "id": "LT000000002",
      "originalIndex": 2,
      "location": {
        "lat": 56.309669,
        "lng": 22.339082
      },
      "matchedAddress": "Gamyklos g. 1, LT-89231 Mažeikiai",
      "relevance": 0.4505,
      "arrivalTime": "11:07"
    },
    {
      "id": null,
      "originalIndex": 8,
      "location": {
        "lat": 56.30294,
        "lng": 22.34013
      },
      "arrivalTime": "11:11"
    }
  ],
  "routes": [
    {
      "duration": 11499.399,
      "distance": 186.143,
      "legs": [
        {
          "duration": 2496.325,
          "distance": 48.265,
          "geometry": "wnmkjB..."
        },
        {
          "duration": 1792.493,
          "distance": 34.289,
          "geometry": "{qjwiB..."
        },
        {
          "duration": 286.13,
          "distance": 3.156,
          "geometry": "ybnsiB..."
        },
        {
          "duration": 3533.614,
          "distance": 64.865,
          "geometry": "majsiB..."
        },
        {
          "duration": 1512.977,
          "distance": 21.951,
          "geometry": "yk`ojB..."
        },
        {
          "duration": 471.583,
          "distance": 6.906,
          "geometry": "{dzkjB..."
        },
        {
          "duration": 454.142,
          "distance": 5.815,
          "geometry": "kd|mjB..."
        },
        {
          "duration": 112.133,
          "distance": 0.893,
          "geometry": "ojzkjB..."
        }
      ]
    }
  ]
}

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}`);
});