​
Overview

Time windows define when jobs can be serviced, ensuring resources arrive within specified time ranges. This feature enables you to meet customer expectations, comply with delivery agreements, and optimize routes while respecting temporal constraints.
The VRP solver automatically ensures resources arrive at the beginning of time windows, eliminating early arrivals and unnecessary waiting.

​
Time Window Configuration

​
Basic Structure

Each job can have multiple time windows, providing flexibility for service scheduling: 
{
  "name": "delivery-123",
  "duration": 3600,
  "windows": [
    {
      "from": "2023-01-02T09:00:00",
      "to": "2023-01-02T10:00:00",
      "hard": true,
      "weight": 100
    }
  ]
}

​
Window Properties

​
from
string
required
Start time of the window in ISO 8601 format. The resource cannot arrive before this time.
​
to
string
required
End time of the window in ISO 8601 format. The resource must arrive before this time.
​
hard
boolean
default:"true"
Whether violating this window makes the solution infeasible. Hard windows must be respected.
​
weight
integer
default:"1"
Penalty weight applied when soft windows are violated. Higher values increase violation cost.

​
Complete Example

This example demonstrates time window usage with partial planning enabled, showing how some jobs may remain unassigned due to time constraints. 
{
  "resources": [
    {
      "name": "R-1",
      "shifts": [
        {
          "from": "2023-01-01T08:00:00",
          "to": "2023-01-01T17:00:00"
        },
        {
          "from": "2023-01-02T08:00:00",
          "to": "2023-01-02T17:00:00"
        }
      ]
    }
  ],
  "jobs": [
    {
      "name": "JOB-1",
      "location": {
        "latitude": 50.54963315022148,
        "longitude": 4.848855475505483
      },
      "duration": 3600,
      "windows": [
        {
          "from": "2023-01-02T09:00:00",
          "to": "2023-01-02T10:00:00",
          "hard": true,
          "weight": 100
        }
      ]
    },
    {
      "name": "JOB-2",
      "location": {
        "latitude": 50.65910297910443600,
        "longitude": 4.007987934186738
      },
      "duration": 3600,
      "windows": [
        {
          "from": "2023-01-02T09:30:00",
          "to": "2023-01-02T10:30:00",
          "hard": true,
          "weight": 100
        }
      ]
    },
    {
      "name": "JOB-3",
      "location": {
        "latitude": 50.324969095932296,
        "longitude": 4.010111317974326
      },
      "duration": 3600
      // No time window - can be scheduled anytime
    },
    // Additional jobs 4-10...
  ],
  "options": {
    "partialPlanning": true
  }
}

​
Key Insights

​
Why JOB-1 Was Unassigned

JOB-1 required service between 09:00-10:00 on 2023-01-02, but the route structure made it impossible to reach this location within the time window while also servicing JOB-2 (09:30-10:30).
The solver prioritized JOB-2 over JOB-1 based on overall route efficiency and the ability to service more total jobs.

​
Route Optimization Strategy

The solver:
  1. Grouped jobs without time windows on Day 1 for maximum flexibility
  2. Scheduled time-windowed jobs on Day 2 where feasible
  3. Optimized travel paths to minimize total distance
  4. Left JOB-1 unassigned rather than violating hard constraints

​
Time Window Patterns

​
Single Narrow Window

For strict appointment times: 
{
  "windows": [{
    "from": "2023-01-15T14:00:00",
    "to": "2023-01-15T14:30:00",
    "hard": true
  }]
}

​
Multiple Windows

For flexible scheduling options: 
{
  "windows": [
    {
      "from": "2023-01-15T09:00:00",
      "to": "2023-01-15T12:00:00",
      "hard": true
    },
    {
      "from": "2023-01-15T14:00:00",
      "to": "2023-01-15T17:00:00",
      "hard": true
    }
  ]
}

​
Soft Windows with Preferences

For preferred but flexible timing: 
{
  "windows": [
    {
      "from": "2023-01-15T09:00:00",
      "to": "2023-01-15T10:00:00",
      "hard": false,
      "weight": 50  // Moderate preference
    },
    {
      "from": "2023-01-15T08:00:00",
      "to": "2023-01-15T17:00:00",
      "hard": true  // Must be within business hours
    }
  ]
}

​
Best Practices

1

Use realistic window sizes

Allow sufficient time for travel and service. Overly narrow windows reduce routing flexibility and may lead to unassigned jobs.
2

Combine hard and soft windows

Use soft windows for preferences and hard windows for absolute requirements. This provides flexibility while meeting critical constraints.
3

Consider travel time

Account for realistic travel times between locations when setting consecutive time windows.
4

Enable partial planning

Set partialPlanning: true when time windows might make complete assignment impossible. This prevents infeasible solutions.

​
Common Pitfalls

When multiple jobs have overlapping time windows in the same area, ensure there’s enough capacity to service them all:
// Problematic: Both require 09:00-10:00 slot
[
  {"name": "job1", "windows": [{"from": "09:00", "to": "10:00"}]},
  {"name": "job2", "windows": [{"from": "09:00", "to": "10:00"}]}
]

// Better: Stagger the windows
[
  {"name": "job1", "windows": [{"from": "09:00", "to": "10:00"}]},
  {"name": "job2", "windows": [{"from": "10:00", "to": "11:00"}]}
]
Avoid setting windows that are physically impossible to achieve:
// Impossible: 30 minutes apart, 60 minutes travel time
{
  "job1": {
    "location": "cityA",
    "windows": [{"from": "09:00", "to": "09:30"}]
  },
  "job2": {
    "location": "cityB",  // 60 min from cityA
    "windows": [{"from": "09:30", "to": "10:00"}]
  }
}

Job Relations

Enforce sequencing between time-windowed jobs

Shift Management

Configure resource availability windows

Priority Jobs

Prioritize time-sensitive deliveries

Partial Planning

Handle scenarios where not all jobs can be assigned