{
  "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
  }
}

​
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

{
  "options": {
    "snapUnit": 300  // Professional services
  }
}
For businesses with flexible scheduling

​
Impact on Routes

1

Calculate Natural Arrival

Solver determines optimal arrival time
2

Apply Snap Rounding

Round up to next snapUnit interval
3

Add Wait Time

Driver waits if arrived before snapped time
4

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

{
  "name": "equipment-service",
  "duration": 1800,  // 30 min service
  "padding": 600     // 10 min setup/cleanup
}
Total time blocked: 50 minutes
{
  "name": "home-delivery",
  "duration": 300,   // 5 min delivery
  "padding": 180     // 3 min for customer to answer
}
Ensures customer readiness
{
  "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):
  1. Natural arrival: 9:03
  2. Snapped arrival: 9:15
  3. Actual service start: 9:20 (after padding)
  4. Service end: 10:20
  5. 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

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

​
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

1

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
2

Create Period Matrices

Generate distance matrices for each period with realistic travel times
3

Configure Transitions

Solver automatically interpolates between periods
4

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

  1. Morning appointment:
    • Natural arrival: 8:12
    • Snapped to: 8:15
    • Service: 8:20-9:05 (with padding)
    • Depart: 9:10
  2. 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

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

1

Choose Appropriate Precision

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

Balance Features

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

Monitor Wait Time

  • Track wait time statistics
  • Adjust snapUnit if excessive waiting
4

Validate Time Logic

  • Ensure padding + duration fits in windows
  • Check overtime doesn’t conflict with shifts

​
Troubleshooting

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