Skip to main content
POST
/
v1
/
routing
/
optimized_route
Optimized Route
curl --request POST \
  --url https://api.bookovia.com/v1/routing/optimized_route \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "locations": [
    {
      "lat": 123,
      "lon": 123
    }
  ],
  "costing": "<string>",
  "costing_options": {}
}
'
{
  "success": true,
  "data": {
    "trip": {
      "locations": [
        {}
      ],
      "legs": [
        {}
      ],
      "summary": {
        "length": 123,
        "time": 123
      }
    }
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.bookovia.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Optimized Route endpoint solves the Traveling Salesman Problem (TSP) to find the most efficient order for visiting multiple locations. This is ideal for delivery routes, service calls, and multi-stop trips where the stop order can be flexible.
This endpoint automatically reorders intermediate waypoints to minimize total travel time or distance. The first and last locations remain fixed.

​
Authentication

This endpoint requires authentication via API key in the X-API-Key header. Required permissions: routing:read

​
Request

​
locations
array
required
Array of locations to visit (minimum 4, maximum 50). The first location is the start point, the last is the end point, and all intermediate locations will be reordered for optimization.
​
costing
string
required
Transportation mode for routing calculationOptions: auto, truck, bicycle, pedestrian, motorcycle, motor_scooter, bus, taxiDefault: auto
​
costing_options
object
Mode-specific routing preferences (same options as /route endpoint)

​
Request Example

curl -X POST https://api.bookovia.com/v1/routing/optimized_route \
  -H "X-API-Key: bkv_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 40.7128, "lon": -74.0060},
      {"lat": 40.7589, "lon": -73.9851},
      {"lat": 40.7614, "lon": -73.9776},
      {"lat": 40.7831, "lon": -73.9712},
      {"lat": 40.7489, "lon": -73.9680}
    ],
    "costing": "auto"
  }'

​
Response

​
success
boolean
Indicates whether the request was successful
​
data
object
Optimized route with reordered locations

​
Response Example

{
  "success": true,
  "data": {
    "trip": {
      "locations": [
        {"lat": 40.7128, "lon": -74.0060, "original_index": 0},
        {"lat": 40.7489, "lon": -73.9680, "original_index": 4},
        {"lat": 40.7614, "lon": -73.9776, "original_index": 2},
        {"lat": 40.7831, "lon": -73.9712, "original_index": 3},
        {"lat": 40.7589, "lon": -73.9851, "original_index": 1}
      ],
      "legs": [...],
      "summary": {
        "length": 12.3,
        "time": 1800
      }
    }
  }
}

​
Use Cases

Optimize delivery routes for couriers, food delivery, and package services. Reduces fuel costs and delivery time by finding the best visit order.
Optimize technician routes for service calls, installations, and repairs. Maximize daily capacity by minimizing travel between appointments.
Plan efficient routes for sales representatives visiting multiple clients. Optimize by drive time to maximize face-to-face meeting time.
Help users plan errands efficiently. Optimize stops for grocery shopping, pickups, appointments to save time and fuel.

​
Algorithm Details

The optimization algorithm considers:
  • Travel time between all location pairs
  • Distance between all stops
  • Road network topology (actual driving routes, not straight-line distances)
  • Traffic patterns (if time-based routing is enabled)
The algorithm uses a heuristic approach optimized for speed. For 10-20 stops, results are typically within 5% of the mathematically optimal solution and compute in under 2 seconds.

​
Limitations

Minimum 4 locations required: The optimization requires at least 4 locations (start + 2 intermediate stops + end). For 2-3 locations, use the standard /route endpoint.
Maximum 50 locations: The endpoint supports up to 50 locations. For larger problems, consider breaking into multiple sub-routes or using batch optimization.