Advanced Time Features

Beyond basic time windows and scheduling, the VRP solver offers advanced time features for precise control over arrival times, service scheduling, and multi-day optimization. This guide covers snapUnit, job padding, overtime management, and traffic-aware routing.

Time Snapping (snapUnit)

Round arrival times to specific intervals for cleaner schedules:

{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "delivery-1",
      "duration": 1800
    }
  ],
  "options": {
    "snapUnit": 900  // 15-minute intervals
  }
}

How snapUnit Works

Snap Behavior: Arrival times are rounded UP to the nearest snapUnit interval.

Actual arrival: 9:03 → Snapped to: 9:15
Actual arrival: 9:15 → Stays at: 9:15
Actual arrival: 9:16 → Snapped to: 9:30

Common snapUnit Values

5 Minutes
15 Minutes
30 Minutes
1 Hour

{
  "options": {
    "snapUnit": 300  // Professional services
  }
}

For businesses with flexible scheduling

{
  "options": {
    "snapUnit": 900  // Standard appointments
  }
}

Most common for service industries

{
  "options": {
    "snapUnit": 1800  // Block scheduling
  }
}

For longer appointments or deliveries

{
  "options": {
    "snapUnit": 3600  // Hourly slots
  }
}

Simple scheduling for low-precision needs

Impact on Routes

Calculate Natural Arrival

Solver determines optimal arrival time

Apply Snap Rounding

Round up to next snapUnit interval

Add Wait Time

Driver waits if arrived before snapped time

Start Service

Begin job at snapped arrival time

Job Padding

Delay the arrival at a job by a fixed buffer, for example to reserve time to park, check in, or prepare:

{
  "resources": [
    {
      "name": "technician-1",
      "shifts": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "complex-installation",
      "duration": 3600,  // 1 hour service
      "padding": 300,    // arrival is postponed by 5 minutes
      "location": {
        "latitude": 51.0543,
        "longitude": 3.7174
      }
    }
  ]
}

Padding Use Cases

Setup Time

{
  "name": "equipment-service",
  "duration": 1800,  // 30 min service
  "padding": 600     // 10 min setup before service starts
}

Service starts 10 minutes after the natural arrival, when the job is not first in the trip

Customer Preparation

{
  "name": "home-delivery",
  "duration": 300,   // 5 min delivery
  "padding": 180     // 3 min for customer to answer
}

Ensures customer readiness

Safety Buffer

{
  "name": "medical-appointment",
  "duration": 2700,  // 45 min appointment
  "padding": 900     // 15 min safety margin on arrival
}

Builds slack into the arrival at this job

Padding vs snapUnit Interaction

Important: Padding is applied AFTER snap calculations. It postpones the arrival at the job (after travel), so it has no effect on the first job of a trip. Padding is not added after the service ends: the next leg starts when the service ends.Example with snapUnit=900 (15 min) and padding=300 (5 min), for a job that is not first in its trip:

Natural arrival: 9:03
Snapped arrival: 9:15
Actual service start: 9:20 (after padding)
Service end: 10:20
Travel to the next job starts: 10:20

Advanced Overtime Management

Configure flexible overtime with graduated penalties:

{
  "resources": [{
    "name": "driver-1",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "overtimeEnd": "2024-03-15T20:00:00Z"
    }],
    "hourlyCost": 25
  }],
  "jobs": [{
    "name": "late-job",
    "duration": 3600
  }],
  "weights": {
    "overtimeWeight": 100
  }
}

Overtime Strategies

Simple Overtime
Graduated Penalties
Hard Cutoff

{
  "shifts": [{
    "from": "2024-03-15T08:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "overtimeEnd": "2024-03-15T19:00:00Z"
  }],
  "hourlyCost": 30
}

{
  "shifts": [{
    "from": "2024-03-15T08:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "overtimeEnd": "2024-03-15T20:00:00Z"
  }],
  "weights": {
    "overtimeWeight": 100
  }
}

{
  "shifts": [{
    "from": "2024-03-15T08:00:00Z",
    "to": "2024-03-15T17:00:00Z",
    "overtimeEnd": "2024-03-15T18:00:00Z"  // 1 hour max, nothing is planned after this
  }]
}

overtimeEnd is the hard stop. overtimeWeight only controls how reluctant the solver is to use the time between to and overtimeEnd.

Time-Dependent Routing

Travel times can depend on the time of day. Which behaviour you get is set by options.routingEngine:

`routingEngine`	Travel times
`OSM` (default)	Static, they do not change with the time of day
`TOMTOM`, `GOOGLE`, `ANYMAP`	Can vary with the departure time
`TOMTOM_REAL_TIME`	Based on current traffic, regardless of the planned departure time

{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T06:00:00Z",
        "to": "2024-03-15T19:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "morning-delivery",
      "location": {"latitude": 51.0543, "longitude": 3.7174},
      "duration": 1800,
      "windows": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T10:00:00Z"
      }]
    },
    {
      "name": "afternoon-delivery",
      "location": {"latitude": 51.2194, "longitude": 4.4025},
      "duration": 1800,
      "windows": [{
        "from": "2024-03-15T14:00:00Z",
        "to": "2024-03-15T16:00:00Z"
      }]
    }
  ],
  "options": {
    "routingEngine": "TOMTOM"
  }
}

If you only need a rough allowance for congestion, set options.traffic instead. It is a global multiplier on all travel times (for example 1.1 adds 10%).

Custom Distance Matrices

If you have pre-computed distance matrices, reference them with customDistanceMatrices instead of letting the solver call a routing engine. profileMatrices maps a vehicle profile (CAR, BIKE, TRUCK) to the matrix ID to use for each time slice, keyed by the start hour of the slice (6, 9, 12, 14, 16, 20):

{
  "customDistanceMatrices": {
    "profileMatrices": {
      "CAR": {
        "6": "matrix-car-morning-123",
        "9": "matrix-car-midday-456",
        "16": "matrix-car-evening-789"
      }
    }
  }
}

Multi-Day ASAP Optimization

Schedule jobs as early as possible across multiple days:

{
  "jobs": [
    {
      "name": "flexible-service",
      "windows": [
        {"from": "2024-03-15T08:00:00Z", "to": "2024-03-15T17:00:00Z"},
        {"from": "2024-03-16T08:00:00Z", "to": "2024-03-16T17:00:00Z"},
        {"from": "2024-03-17T08:00:00Z", "to": "2024-03-17T17:00:00Z"}
      ]
    },
    {
      "name": "scheduled-later",
      "windows": [
        {"from": "2024-03-17T08:00:00Z", "to": "2024-03-17T17:00:00Z"},
        {"from": "2024-03-18T08:00:00Z", "to": "2024-03-18T17:00:00Z"}
      ]
    }
  ],
  "weights": {
    "asapWeight": 100
  }
}

ASAP Scheduling Logic

There is no dedicated “earliest day” job field. Instead, the earliest day a job can be scheduled is expressed entirely through its windows: a job’s first window determines when it becomes available, and jobs with no early window (like scheduled-later, whose earliest window starts on day 3) simply cannot be scheduled sooner.weights.asapWeight then creates pressure for the solver to prefer a job’s earliest available window over a later one, for any job that has more than one window to choose from.

Complex Time Scenario

Combining all advanced time features:

{
  "options": {
    "snapUnit": 900  // 15-minute slots
  },
  "weights": {
    "asapWeight": 80,
    "overtimeWeight": 100,
    "waitTimeWeight": 20,
    "urgencyWeight": 50  // urgency has no effect while this is 0 (the default)
  },
  "jobs": [
    {
      "name": "morning-appointment",
      "duration": 2700,  // 45 minutes
      "padding": 300,    // 5 min buffer on arrival
      "windows": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T12:00:00Z"
      }]
    },
    {
      "name": "afternoon-installation",
      "duration": 7200,  // 2 hours
      "padding": 600,    // 10 min setup
      "urgency": 90,
      "windows": [{
        "from": "2024-03-15T13:00:00Z",
        "to": "2024-03-15T17:00:00Z"
      }]
    }
  ],
  "resources": [{
    "name": "technician",
    "shifts": [{
      "from": "2024-03-15T08:00:00Z",
      "to": "2024-03-15T17:00:00Z",
      "overtimeEnd": "2024-03-15T19:00:00Z"
    }]
  }]
}

Expected Behavior

Morning appointment (first job of the trip, so its padding has no effect):
- Natural arrival: 8:12
- Snapped to: 8:15
- Service: 8:15-9:00
- Depart: 9:00
Afternoon installation (not first, so its padding delays the arrival):
- Natural arrival: 13:08
- Snapped to: 13:15
- Service: 13:25-15:25 (after 10 minutes of padding)
- Depart: 15:25

Performance Optimization

Time Feature Impact

Performance Considerations

Low Impact:

snapUnit with reasonable intervals (≥300s)
Simple padding values
Basic overtime configuration

Medium Impact:

Small snapUnit values (< 300s)
Complex overtime structures

High Impact:

Very small snapUnit (60s)

Best Practices

Choose Appropriate Precision

Use 15-minute slots unless finer control needed
Avoid snapUnit < 300 for large problems

Balance Features

Don’t combine all features unless necessary
Test impact of each feature separately

Monitor Wait Time

Track wait time statistics
Adjust snapUnit if excessive waiting

Validate Time Logic

Ensure the arrival after padding, plus the duration, fits in the window
Check overtime doesn’t conflict with shifts

Troubleshooting

Excessive Wait Times

Symptom: Drivers waiting long periodsCauses:

snapUnit too large
Poor alignment with job windows
Suboptimal route sequencing

Solutions:

Reduce snapUnit value
Adjust time windows
Increase waitTimeWeight

Jobs Not Fitting in Windows

Symptom: Jobs unassigned due to timeCauses:

Padding postpones the arrival past the end of the window
snapUnit pushes beyond window
Travel time underestimated

Solutions:

Reduce padding
Widen time windows
Verify travel time accuracy

Unexpected Overtime

Symptom: Routes extending past regular hoursCauses:

snapUnit delaying arrivals
Padding accumulating
Poor ASAP prioritization

Solutions:

Increase overtimeWeight
Review time feature combinations
Adjust shift definitions

Time Windows

Core time scheduling features

Cost Optimization

Overtime cost configuration

Break Management

How breaks interact with timing

Multi-Day Planning

Extended planning horizons

Platform

VRP API

Fill API

Advanced Time Features

Advanced Time Features

Time Snapping (snapUnit)

How snapUnit Works

Common snapUnit Values

Impact on Routes

Job Padding

Padding Use Cases

Padding vs snapUnit Interaction

Advanced Overtime Management

Overtime Strategies

Time-Dependent Routing

Custom Distance Matrices

Multi-Day ASAP Optimization

ASAP Scheduling Logic

Complex Time Scenario

Expected Behavior

Performance Optimization

Time Feature Impact

Best Practices

Troubleshooting

Time Windows

Cost Optimization

Break Management

Multi-Day Planning

​Advanced Time Features

​Time Snapping (snapUnit)

​How snapUnit Works

​Common snapUnit Values

​Impact on Routes

​Job Padding

​Padding Use Cases

​Padding vs snapUnit Interaction

​Advanced Overtime Management

​Overtime Strategies

​Time-Dependent Routing

​Custom Distance Matrices

​Multi-Day ASAP Optimization

​ASAP Scheduling Logic

​Complex Time Scenario

​Expected Behavior

​Performance Optimization

​Time Feature Impact

​Best Practices

​Troubleshooting

​Related Features

Time Windows

Cost Optimization

Break Management

Multi-Day Planning

Advanced Time Features

Time Snapping (snapUnit)

How snapUnit Works

Common snapUnit Values

Impact on Routes

Job Padding

Padding Use Cases

Padding vs snapUnit Interaction

Advanced Overtime Management

Overtime Strategies

Time-Dependent Routing

Custom Distance Matrices

Multi-Day ASAP Optimization

ASAP Scheduling Logic

Complex Time Scenario

Expected Behavior

Performance Optimization

Time Feature Impact

Best Practices

Troubleshooting

Related Features