Skip to main content
POST
/
v1
/
routing
/
route
Get Route
curl --request POST \
  --url https://api.bookovia.com/v1/routing/route \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "locations": [
    {
      "lat": 123,
      "lon": 123,
      "type": "<string>",
      "heading": 123,
      "heading_tolerance": 123,
      "street_side_tolerance": 123
    }
  ],
  "costing": "<string>",
  "costing_options": {
    "maneuver_penalty": 123,
    "use_highways": 123,
    "use_tolls": 123,
    "use_ferry": 123,
    "top_speed": 123,
    "exclude_unpaved": true,
    "exclude_cash_only_tolls": true,
    "shortest": true,
    "height": 123,
    "width": 123,
    "length": 123,
    "weight": 123,
    "axle_load": 123,
    "axle_count": 123,
    "hazmat": true,
    "use_truck_route": true,
    "bicycle_type": "<string>",
    "cycling_speed": 123,
    "use_roads": 123,
    "use_hills": 123,
    "avoid_bad_surfaces": 123,
    "use_bike_lanes": 123,
    "walking_speed": 123,
    "walkway_factor": 123,
    "sidewalk_factor": 123,
    "step_penalty": 123,
    "max_hiking_difficulty": 123
  },
  "directions_options": {
    "units": "<string>",
    "language": "<string>",
    "directions_type": "<string>",
    "format": "<string>"
  },
  "alternates": 123,
  "date_time": {
    "type": 123,
    "value": "<string>"
  }
}
'
{
  "success": true,
  "data": {
    "trip": {
      "locations": [
        {}
      ],
      "legs": [
        {
          "maneuvers": [
            {
              "type": 123,
              "instruction": "<string>",
              "street_names": [
                {}
              ],
              "length": 123,
              "time": 123,
              "begin_shape_index": 123,
              "end_shape_index": 123,
              "verbal_pre_transition_instruction": "<string>",
              "verbal_post_transition_instruction": "<string>"
            }
          ],
          "summary": {
            "length": 123,
            "time": 123
          },
          "shape": "<string>"
        }
      ],
      "summary": {
        "length": 123,
        "time": 123,
        "min_lat": 123,
        "max_lat": 123,
        "min_lon": 123,
        "max_lon": 123
      }
    }
  },
  "error": "<string>",
  "details": "<string>"
}

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 Route endpoint computes optimal routes between waypoints using real-time traffic data and advanced routing algorithms. It supports multiple transportation modes, vehicle restrictions, and route preferences to provide accurate navigation instructions.
Built on Overture Maps data with 62M+ road segments and 88M intersection nodes covering the entire United States.

Authentication

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

Request

locations
array
required
Array of waypoint locations (minimum 2, maximum 50). Routes will be calculated in the order provided.
costing
string
required
Transportation mode for routing calculationOptions: auto, auto_shorter, truck, bicycle, pedestrian, motorcycle, motor_scooter, bus, taxi, bikeshareDefault: auto
costing_options
object
Mode-specific routing preferences and vehicle constraints
directions_options
object
Output format and display preferences
alternates
integer
Number of alternative routes to return (0-2)Default: 0
date_time
object
Time-based routing for traffic-aware calculations

Request Example

curl -X POST https://api.bookovia.com/v1/routing/route \
  -H "X-API-Key: bkv_test_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "locations": [
      {"lat": 40.7128, "lon": -74.0060, "type": "break"},
      {"lat": 40.7589, "lon": -73.9851, "type": "break"}
    ],
    "costing": "auto",
    "costing_options": {
      "auto": {
        "use_tolls": 0.0,
        "use_highways": 1.0,
        "exclude_unpaved": true
      }
    },
    "directions_options": {
      "units": "miles",
      "language": "en"
    },
    "alternates": 1
  }'

Response

success
boolean
Indicates whether the request was successful
data
object
Route calculation result

Response Example

{
  "success": true,
  "data": {
    "trip": {
      "locations": [
        {
          "lat": 40.712799,
          "lon": -74.006,
          "type": "break",
          "side_of_street": "right"
        },
        {
          "lat": 40.758899,
          "lon": -73.985103,
          "type": "break",
          "side_of_street": "right"
        }
      ],
      "legs": [
        {
          "maneuvers": [
            {
              "type": 1,
              "instruction": "Drive north on Broadway",
              "street_names": ["Broadway"],
              "length": 0.5,
              "time": 45,
              "begin_shape_index": 0,
              "end_shape_index": 12,
              "verbal_pre_transition_instruction": "Drive north on Broadway for 5 blocks.",
              "verbal_post_transition_instruction": "Continue for 5 blocks."
            },
            {
              "type": 15,
              "instruction": "Turn right onto West 42nd Street",
              "street_names": ["West 42nd Street"],
              "length": 0.3,
              "time": 60,
              "begin_shape_index": 12,
              "end_shape_index": 24
            },
            {
              "type": 4,
              "instruction": "Your destination is on the right",
              "length": 0.0,
              "time": 0,
              "begin_shape_index": 24,
              "end_shape_index": 24
            }
          ],
          "summary": {
            "length": 5.8,
            "time": 720
          },
          "shape": "encoded_polyline_string_here"
        }
      ],
      "summary": {
        "length": 5.8,
        "time": 720,
        "min_lat": 40.7128,
        "max_lat": 40.7589,
        "min_lon": -74.0060,
        "max_lon": -73.9851
      }
    }
  }
}

Use Cases

Generate voice-guided navigation instructions for mobile apps and in-vehicle systems. Supports real-time rerouting and traffic-aware ETAs.
Calculate optimal routes for commercial vehicles with truck-specific restrictions (height, weight, hazmat). Avoid low bridges and weight-restricted roads.
Plan delivery routes with up to 50 waypoints. Control stop order with type: break vs type: through for efficient multi-drop routing.
Provide safe cycling and walking directions that prefer bike lanes, trails, and sidewalks. Avoid high-traffic roads and steep hills based on user preferences.
Calculate routes based on departure or arrival time to account for traffic patterns, ferry schedules, and time-sensitive restrictions.
Offer users 2-3 route options with different characteristics (fastest vs shortest, avoid tolls vs use highways). Let users choose based on preferences.

Error Handling

error
string
Error message if the request failed
details
string
Detailed error information from routing engine

Common Errors

Status CodeErrorDescription
400Invalid request bodyMalformed JSON or missing required fields
400No route foundNo valid route between locations (disconnected roads, water barrier, etc.)
400Distance exceeds maximumRoute distance exceeds 5,000 km limit
400Too many locationsMore than 50 waypoints provided
401API key requiredMissing X-API-Key header
401Invalid API key formatAPI key doesn’t start with bkv_
500Routing request failedInternal routing engine error
Rate Limits: This endpoint has a rate limit of 1,000 requests per minute per API key. Exceeding this limit will result in 429 Too Many Requests responses.

Best Practices

Optimize for performance: Request only the data you need by setting directions_type: "none" if you only need distance/time, or directions_type: "maneuvers" if you don’t need voice instructions.
Handle no-route scenarios: Always check for route failure and provide fallback options (e.g., suggest nearby pickup points if exact address isn’t routable).
Cache routes: Cache commonly requested routes to reduce API calls and improve response times. Routes are generally stable unless road closures occur.
Use appropriate costing: Match the costing model to your use case. Use auto_shorter for urban deliveries, truck for commercial vehicles, bicycle for bike-sharing apps.