Distance Matrix Integration

The VRP solver integrates with Solvice Maps to generate distance matrices before optimization, so routes are based on real travel times and distances instead of straight-line estimates.

Why It Matters

Without real distance data, the solver falls back to euclidean (straight-line) distances with no traffic or route restrictions — which can produce routes that look optimal on paper but aren’t actually drivable.

How It Works

Before solving, the VRP solver collects every unique job and resource location from your request and fetches a distance matrix for them from Solvice Maps, then uses the resulting durations and distances during optimization. Request splitting for large location sets and vehicle-category mapping are handled automatically.

Available Routing Options

Euclidean vs Real Road Networks

Euclidean Distance
Real Road Networks

{ "options": { "euclidian": true } }

Straight-line distances — fast, no external dependency, less accurate. Good for prototyping.

{ "options": { "euclidian": false, "routingEngine": "OSM" } }

Real road-network distances (default). Slower to compute, accurate enough for production.

Routing Engine Selection

{ "options": { "routingEngine": "OSM" } }

{ "options": { "routingEngine": "TOMTOM" } }

{
  "options": {
    "routingEngine": "TOMTOM_REAL_TIME"
  }
}

OSM: OpenStreetMap data, global coverage, no traffic awareness
TOMTOM: Commercial routing with traffic data for enhanced accuracy
TOMTOM_REAL_TIME: TomTom routing on live traffic conditions - see Live traffic

Custom Distance Matrices

Instead of letting the VRP solver compute a distance matrix for you, you can supply your own pre-computed matrix and have the solver use it as-is. This is useful when:

You’ve already generated a matrix for a recurring set of locations and want to skip recomputing it on every request
You need routing constraints that aren’t achievable through routingEngine and vehicle category alone
Matrix generation time is a significant part of your total solve time and you want to remove it from the critical path

When a custom matrix is supplied for a vehicle profile and time slice, the solver uses it instead of computing a fresh matrix through the routing engine. Every leg’s distance and duration for that profile comes directly from your matrix.

The `customDistanceMatrices` Field

{
  "customDistanceMatrices": {
    "profileMatrices": {
      "CAR": {
        "20": "16150006"
      }
    }
  }
}

object

Maps a vehicle profile name (matching a resource’s category, e.g. CAR, BIKE, TRUCK) to a set of time-slice-hour → matrix ID pairs. The matrix ID must reference a table that has already finished computing.

string

Optional URL for an external distance matrix service endpoint. If omitted, the default system service is used.

Time Slice Hours

Hour	Slice
`6`	MORNING_RUSH
`9`	MORNING
`12`	MIDDAY
`14`	AFTERNOON
`16`	EVENING_RUSH
`20`	NIGHT

When routingEngine is OSM (the default), the solver only fetches the NIGHT slice ("20") — a single matrix ID per profile is enough. Traffic-aware engines (TOMTOM, ANYMAP) can use a different matrix per slice to cover the full day.

Generating a Matrix ID

Matrix IDs come from Solvice Maps’ Matrix endpoint, not from the VRP API itself:

Request a table

curl -X POST https://routing.solvice.io/table \
  -H "Authorization: <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "coordinates": [[4.4111, 51.2219], [4.3391, 51.2154]],
    "annotations": ["duration", "distance"],
    "vehicleType": "CAR"
  }'

Returns a table id with "status": "IN_PROGRESS".

Poll until it's ready

curl https://routing.solvice.io/table/<id> \
  -H "Authorization: <api-key>"

Wait until "status" becomes "SUCCEEDED".

Reference the ID in your VRP request

Use that same id as the matrix ID in customDistanceMatrices.profileMatrices.

Full Example

{
  "jobs": [
    {
      "name": "visit-1",
      "location": { "latitude": 51.2154, "longitude": 4.3391 }
    }
  ],
  "resources": [
    {
      "name": "R1",
      "start": { "latitude": 51.2219, "longitude": 4.4111 },
      "category": "CAR",
      "shifts": [
        { "from": "2024-03-15T08:00:00Z", "to": "2024-03-15T20:00:00Z" }
      ]
    }
  ],
  "options": {
    "routingEngine": "OSM"
  },
  "customDistanceMatrices": {
    "profileMatrices": {
      "CAR": {
        "20": "16150006"
      }
    }
  }
}

Traffic Multiplier

{ "options": { "traffic": 1.2 } }

A flat multiplier applied to every leg’s travel time (1.2 = +20%) — a simple approximation when you don’t have per-route traffic data. For real time-of-day traffic, use routingEngine: "TOMTOM", or supply your own time-sliced data via Custom Distance Matrices.

Live traffic

TOMTOM predicts travel times from historical patterns for the departureTime you supply. TOMTOM_REAL_TIME instead uses traffic conditions at the moment of the request:

{
  "options": {
    "routingEngine": "TOMTOM_REAL_TIME"
  }
}

Use it when you dispatch on the result immediately. To plan a shift that starts later in the day, use TOMTOM with a departureTime — TOMTOM_REAL_TIME ignores departureTime and always routes on the current time.

TOMTOM_REAL_TIME returns travel times only, not road distances. totalTravelDistanceInMeters reports 0, and costs.distanceCostPerKm and weights.distanceWeight have no effect on the solution. Choose TOMTOM when your optimization depends on distance.

Requests are limited to 49 unique locations. Jobs, resource start and end locations, shift start and end locations, unavailability break locations, and depots all count toward that total, and locations sharing coordinates count once. Exceeding the limit returns a 400.

Vehicle Categories

{
  "resources": [
    { "name": "delivery_van", "category": "CAR" },
    { "name": "freight_truck", "category": "TRUCK" }
  ]
}

Each resource’s category determines which routing profile is used when generating its distance matrix.

Performance

Use euclidian: true while prototyping; switch to real road networks for production
Larger location sets take longer to matrix — factor this into your solve time budget
Consider geographic clustering for very large problems

Error Handling

If the routing engine is unavailable, the solver falls back to euclidean distances rather than failing the request, and reports this via the response’s messages field.

Best Practices

Use real road networks (euclidian: false) in production
Use routingEngine: "TOMTOM" for time-critical, traffic-sensitive routing
Validate a known route’s distance/duration against ground truth before trusting a new routing engine or custom matrix

Basic Routing Example

See distance matrices in practice

Performance Guide

Optimize solving performance

Advanced Time Features

Time-dependent routing capabilities

Constraint System

How constraints use distance data

Platform

VRP API

Fill API

Distance Matrix Integration

Distance Matrix Integration

Why It Matters

How It Works

Available Routing Options

Euclidean vs Real Road Networks

Routing Engine Selection

Custom Distance Matrices

The `customDistanceMatrices` Field

Time Slice Hours

Generating a Matrix ID

Full Example

Traffic Multiplier

Live traffic

Vehicle Categories

Performance

Error Handling

Best Practices

Basic Routing Example

Performance Guide

Advanced Time Features

Constraint System

​Distance Matrix Integration

​Why It Matters

​How It Works

​Available Routing Options

​Euclidean vs Real Road Networks

​Routing Engine Selection

​Custom Distance Matrices

​The customDistanceMatrices Field

​Time Slice Hours

​Generating a Matrix ID

​Full Example

​Traffic Multiplier

​Live traffic

​Vehicle Categories

​Performance

​Error Handling

​Best Practices

​Related Topics

Basic Routing Example

Performance Guide

Advanced Time Features

Constraint System

Distance Matrix Integration

Why It Matters

How It Works

Available Routing Options

Euclidean vs Real Road Networks

Routing Engine Selection

Custom Distance Matrices

The `customDistanceMatrices` Field

Time Slice Hours

Generating a Matrix ID

Full Example

Traffic Multiplier

Live traffic

Vehicle Categories

Performance

Error Handling

Best Practices

Related Topics