Skip to content

Time windows and service duration

Tasks often need to be served within specific hours, and each visit takes a certain amount of time. FastVRP lets you model both through time windows and service durations.

Example

Two tasks in Rotterdam and Amsterdam each require 1 hour of service. Rotterdam has a single morning time window (8:00-10:00), while Amsterdam has two options: a morning (10:00-12:00) and an afternoon slot (15:00-17:00). Service must begin within exactly one of these time windows. A vehicle may arrive before a time window opens and wait, but service cannot begin after the time window closes.

request.json
{
  "locations": [
    {
      "id": "loc-Rotterdam",
      "latitude": 51.9255,
      "longitude": 4.4786
    },
    {
      "id": "loc-Amsterdam",
      "latitude": 52.3676,
      "longitude": 4.9041
    },
    {
      "id": "loc-Utrecht",
      "latitude": 52.0907,
      "longitude": 5.1214
    }
  ],
  "tasks": [
    {
      "id": "task-Rotterdam",
      "location": "loc-Rotterdam",
      "service_duration": "PT3600S",
      "time_windows": [
        {
          "start": "2025-01-01T08:00:00",
          "end": "2025-01-01T10:00:00"
        }
      ]
    },
    {
      "id": "task-Amsterdam",
      "location": "loc-Amsterdam",
      "service_duration": "PT3600S",
      "time_windows": [
        {
          "start": "2025-01-01T10:00:00",
          "end": "2025-01-01T12:00:00"
        },
        {
          "start": "2025-01-01T15:00:00",
          "end": "2025-01-01T17:00:00"
        }
      ]
    }
  ],
  "depots": [
    {
      "id": "depot-Utrecht",
      "location": "loc-Utrecht"
    }
  ],
  "vehicle_types": [
    {
      "id": "vehicle_type",
      "start_depot": "depot-Utrecht",
      "end_depot": "depot-Utrecht",
      "num_available": 1,
      "shift": {
        "earliest_start": "2025-01-01T08:00:00",
        "latest_end": "2025-01-01T18:00:00"
      }
    }
  ],
  "options": {
    "stop": {
      "seconds": 1,
      "type": "max_runtime"
    }
  }
}

When a task has multiple time windows, FastVRP selects the one that best fits the route. Here, the morning window is selected for Amsterdam: visiting Rotterdam first (8:00-10:00) and then Amsterdam (10:00-12:00) avoids the long wait that would result from choosing the afternoon window.

The solution contains detailed information for each activity along the route, including timing, travel duration, and distance from the previous activity.

{
  "id": "depot-Utrecht",
  "type": "depot",
  "start_time": "2025-01-01T08:00:00",
  "end_time": "2025-01-01T08:00:00",
  "duration": "P0D",
  "wait_duration": "P0D",
  "travel_duration": "P0D",
  "distance": 0
}

{
  "id": "task-Rotterdam",
  "type": "task",
  "start_time": "2025-01-01T08:53:47",
  "end_time": "2025-01-01T09:53:47",
  "duration": "PT3600S",
  "wait_duration": "P0D",
  "travel_duration": "PT3227S",
  "distance": 60252
}

{
  "id": "task-Amsterdam",
  "type": "task",
  "start_time": "2025-01-01T10:58:45",
  "end_time": "2025-01-01T11:58:45",
  "duration": "PT3600S",
  "wait_duration": "P0D",
  "travel_duration": "PT3898S",
  "distance": 77853
}

{
  "id": "depot-Utrecht",
  "type": "depot",
  "start_time": "2025-01-01T12:43:11",
  "end_time": "2025-01-01T12:43:11",
  "duration": "P0D",
  "wait_duration": "P0D",
  "travel_duration": "PT2666S",
  "distance": 44340
}

The route summary aggregates these details across all activities and also includes cost information:

Route summary
{
  "total_cost": "4.72",
  "distance_cost": "0.00",
  "duration_cost": "4.72",
  "fixed_vehicle_cost": "0.00",
  "distance": 182445,
  "duration": "PT16991S",
  "travel_duration": "PT9791S",
  "service_duration": "PT7200S",
  "wait_duration": "P0D",
  "start_time": "2025-01-01T08:00:00",
  "end_time": "2025-01-01T12:43:11",
  "num_tasks": 2,
  "num_activities": 4,
  "slack_duration": "PT3675S"
}

The route runs from 08:00 to 12:43, for a total duration of about 4 hours and 43 minutes. The total cost of 4.72 comes entirely from the duration cost (default 1/hour), as no distance or fixed vehicle costs are configured.

Tip

The slack_duration field indicates how much later the vehicle could depart without violating any constraints or increasing the route duration. This is useful for dispatchers who want flexibility in scheduling departure times.

Conclusion

In this tutorial you learned about time windows and service duration. These constraints let you model requirements such as customer availability and service time at each location.