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 time-dependent 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

Add buffer time before and after jobs:

{
  "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,    // 5 minutes before AND after
      "location": {
        "latitude": 51.0543,
        "longitude": 3.7174
      }
    }
  ]
}

Padding Use Cases

Setup/Teardown Time

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

Total time blocked: 50 minutes

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
}

Prevents appointment overruns

Padding vs snapUnit Interaction

Important: Padding is applied AFTER snap calculations.Example with snapUnit=900 (15 min) and padding=300 (5 min):

Natural arrival: 9:03
Snapped arrival: 9:15
Actual service start: 9:20 (after padding)
Service end: 10:20
Ready for next job: 10:25 (after padding)

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
  }],
  "weights": {
    "overtimeWeight": 1000   // Effectively prevents
  }
}

Time-Dependent Routing

Account for traffic patterns and rush hours:

{
  "resources": [
    {
      "name": "driver-1",
      "shifts": [{
        "from": "2024-03-15T06:00:00Z",
        "to": "2024-03-15T19:00:00Z"
      }]
    }
  ],
  "jobs": [
    {
      "name": "morning-delivery",
      "duration": 1800,
      "windows": [{
        "from": "2024-03-15T08:00:00Z",
        "to": "2024-03-15T10:00:00Z"
      }]
    },
    {
      "name": "afternoon-delivery",
      "duration": 1800,
      "windows": [{
        "from": "2024-03-15T14:00:00Z",
        "to": "2024-03-15T16:00:00Z"
      }]
    }
  ],
  "options": {
    "distanceMatrixType": "OSM_ROUTE"
  }
}

Traffic Pattern Modeling

Define Time Periods

Identify distinct traffic patterns:

Morning rush: 6-9 AM
Midday: 9 AM-4 PM
Evening rush: 4-7 PM
Night: 7 PM-6 AM

Create Period Matrices

Generate distance matrices for each period with realistic travel times

Configure Transitions

Solver automatically interpolates between periods

Validate Results

Check routes avoid heavy traffic when possible

Multi-Day ASAP Optimization

Schedule jobs as early as possible across multiple days:

{
  "jobs": [
    {
      "name": "flexible-service",
      "dayIndex": 0,  // Available immediately
      "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",
      "dayIndex": 2,  // Not available until day 3
      "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"}
      ]
    }
  ],
  "options": {
    "weights": {
      "asapWeight": 100,
      "dayIndexWeight": 50
    }
  }
}

DayIndex Logic

dayIndex represents the earliest day a job can be scheduled:

dayIndex: 0 → Can be scheduled on day 1
dayIndex: 1 → Cannot be scheduled before day 2
dayIndex: 2 → Cannot be scheduled before day 3

Combined with asapWeight, this creates pressure to schedule jobs on their earliest available day.

Complex Time Scenario

Combining all advanced time features:

{
  "options": {
    "snapUnit": 900,  // 15-minute slots
    "weights": {
      "asapWeight": 80,
      "overtimeWeight": 100,
      "waitTimeWeight": 20
    }
  },
  "jobs": [
    {
      "name": "morning-appointment",
      "duration": 2700,  // 45 minutes
      "padding": 300,    // 5 min buffer
      "dayIndex": 0,
      "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/cleanup
      "dayIndex": 0,
      "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:
- Natural arrival: 8:12
- Snapped to: 8:15
- Service: 8:20-9:05 (with padding)
- Depart: 9:10
Afternoon installation:
- Natural arrival: 13:08
- Snapped to: 13:15
- Service: 13:25-15:25 (with padding)
- Depart: 15:35

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)
Multiple time-dependent matrices
Complex overtime structures

High Impact:

Very small snapUnit (60s)
Many time period transitions
Complex padding patterns

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 padding + duration fits in windows
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 makes job too long
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

Traffic Pattern Modeling

Multi-Day ASAP Optimization

DayIndex Logic

Complex Time Scenario

Expected Behavior

Performance Optimization

Time Feature Impact

Best Practices

Troubleshooting

Time Windows

Cost Optimization

Break Management

Multi-Day Planning

Platform

VRP API

Fill API

Documentation Index

​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

​Traffic Pattern Modeling

​Multi-Day ASAP Optimization

​DayIndex 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

Traffic Pattern Modeling

Multi-Day ASAP Optimization

DayIndex Logic

Complex Time Scenario

Expected Behavior

Performance Optimization

Time Feature Impact

Best Practices

Troubleshooting

Related Features