Skip to main content
POST
/
v1
/
routing
/
sources_to_targets
Distance Matrix
curl --request POST \
  --url https://api.bookovia.com/v1/routing/sources_to_targets \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "sources": [
    {
      "lat": 123,
      "lon": 123
    }
  ],
  "targets": [
    {
      "lat": 123,
      "lon": 123
    }
  ],
  "costing": "<string>"
}
'
{
  "success": true,
  "data": {
    "sources_to_targets": [
      {
        "distance": 123,
        "time": 123
      }
    ],
    "units": "<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 Distance Matrix endpoint computes routes from multiple source locations to multiple target locations, returning a matrix of distances and times. This is significantly more efficient than calculating each route individually.
Calculate up to 2,500 routes (50 sources × 50 targets) in a single API call. Perfect for batch operations and optimization algorithms.

​
Authentication

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

​
Request

​
sources
array
required
Array of source (origin) locations (maximum 50)
​
targets
array
required
Array of target (destination) locations (maximum 50)
​
costing
string
required
Transportation modeOptions: auto, truck, bicycle, pedestrian

​
Request Example

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

​
Response

​
success
boolean
Indicates whether the request was successful
​
data
object
Distance matrix results

​
Response Example

{
  "success": true,
  "data": {
    "sources_to_targets": [
      [
        {"distance": 5.2, "time": 720},
        {"distance": 3.1, "time": 480},
        {"distance": 2.8, "time": 420}
      ],
      [
        {"distance": 2.1, "time": 300},
        {"distance": 1.5, "time": 240},
        {"distance": 1.2, "time": 180}
      ]
    ],
    "units": "kilometers"
  }
}

​
Use Cases

Match drivers to orders by finding the nearest available driver. Minimize pickup time by calculating distances from all drivers to all pending orders.
Evaluate warehouse locations by calculating delivery times to customer zones. Find optimal locations that minimize average delivery distance.
Match service providers (plumbers, electricians) to customer requests based on drive time. Optimize scheduling to maximize daily service capacity.
Analyze commute times from residential areas to employment centers. Help users find homes with reasonable commutes to their workplace.

​
Performance Tips

Batch wisely: Calculate 50×50 matrices (2,500 routes) instead of 2,500 individual API calls. Reduces cost and latency by ~99%.
Symmetric matrices: If sources and targets are the same, you only need to calculate half the matrix (upper or lower triangle).
  • Optimized Route - Use matrix results as input for TSP optimization
  • Get Route - Get detailed directions for a specific pair