Time Settings

Date and time formats are explicitly defined using the RFC 3339 standard, using a 24-hour clock and offset with respect to UTC (YYYY-MM-DDTHH:MM:SS-UTC). It is a profile of the ISO 8601 international standard.
Durations are defined in seconds.

Time settings define when certain routing events should take place for vehicles and stops. This can include the hours of operation for vehicles, the ideal time a vehicle should service a stop, the exact time a vehicle should service a stop, and how long it takes a vehicle to service a stop. Time settings impact the order in which stops get serviced by vehicles as well as the application of penalties. They are also used to schedule vehicle break times.

Target times

Target times define a specific time a vehicle should service a stop. This time setting is useful for encouraging vehicle timeliness at stops in ride sharing or food transportation scenarios.

Target times are exact times rather than windows or ranges of time. Target times are defined per stop. They are only enforced when earliness and lateness penalties are defined.

JSON

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-10-17T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { "id": "vehicle-1" }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.8128, "lat": 33.02428 },
      // Target delivery time is 9:45am.
      "lateness_penalty": 10,
      "target_time": "2021-10-17T09:45:00-06:00"
    },
    {
      "id": "location-2",
      "position": { "lon": -96.6201, "lat": 33.04621 },
      // Target delivery time is 9:55am.
      "lateness_penalty": 100,
      "target_time": "2021-10-17T09:55:00-06:00"
    },
    {
      "id": "location-3",
      "position": { "lon": -96.9122, "lat": 32.95215 },
      // Target delivery time is 9:35am.
      "lateness_penalty": 10,
      "target_time": "2021-10-17T09:35:00-06:00"
    }
  ]
}

Hard windows

Hard windows are ranges of time a vehicle must service a stop within. This time setting is useful for enforcing strict timeliness for vehicles servicing stops. For example, a ride-sharing service may only want to pick up passengers within a specific time frame to catch a flight at the airport.

Hard windows are hard constraints, i.e., if a stop is assigned to a route it's time window must be met. Otherwise, the stop gets unassigned. Priorities of stops with conflicting windows can be controlled by introducing unassigned penalties. Waiting at a stop for the window to open is allowed by default and can be limited by setting waiting times.

JSON

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-10-17T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { "id": "vehicle-1" }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.8585, "lat": 32.9912 },
      // Delivery must be completed 9:00-10:00am
      "unassigned_penalty": 200000,
      "hard_window": [
        "2021-10-17T09:00:00-06:00", 
        "2021-10-17T10:00:00-06:00"
      ]
    },
    {
      "id": "location-2",
      "position": { "lon": -96.6201, "lat": 33.04621 },
      // Delivery must be completed 9:15-10:15am
      "unassigned_penalty": 100000,
      "hard_window": [
        "2021-10-17T09:15:00-06:00", 
        "2021-10-17T10:15:00-06:00"
      ]
    },
    {
      "id": "location-3",
      "position": { "lon": -96.9122, "lat": 32.95215 },
      // Delivery must be completed 9:30-10:30am
      "unassigned_penalty": 200000,
      "hard_window": [
        "2021-10-17T09:30:00-06:00", 
        "2021-10-17T10:30:00-06:00"
      ]
    }
  ]
}

Waiting times

Waiting time is the maximum amount of time a vehicle is allowed to wait at a stop for the time window to open. For example, a customer was informed about a package delivery between 2 and 4 p.m. Setting a maximum waiting Time (max_wait) to 1800s (30min) the vehicle is allowed to arrive as early as 1:30 p.m. but can start servicing the stop only as soon as the time window opens at 2 p.m.

Waiting time is a hard constraint that is defined at the stop level (default or individually). Note, if waiting time is defined, a hard window must also be defined.

JSON

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-10-17T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { "id": "vehicle-1" }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.8585, "lat": 32.9912 },
      // Delivery must be completed 9:00-10:00am
      // Allow 30 minutes wait time at stop.
      "max_wait": 1800,
      "hard_window": [
        "2021-10-17T09:00:00-06:00", 
        "2021-10-17T10:00:00-06:00"
      ]
    },
    {
      "id": "location-2",
      "position": { "lon": -96.6201, "lat": 33.04621 },
      // Delivery must be completed 9:15-10:15am
      // Allow 30 minutes wait time at stop.
      "max_wait": 1800,
      "hard_window": [
        "2021-10-17T09:15:00-06:00", 
        "2021-10-17T10:15:00-06:00"
      ]
    },
    {
      "id": "location-3",
      "position": { "lon": -96.9122, "lat": 32.95215 },
      // Delivery must be completed 9:30-10:30am
      // Allow 30 minutes wait time at stop.
      "max_wait": 1800,
      "hard_window": [
        "2021-10-17T09:30:00-06:00", 
        "2021-10-17T10:30:00-06:00"
      ]
    }
  ]
}

Shift start and end

Shift start and end indicates a range of time a vehicle is available to service stops. This time setting is useful for enforcing availability of a given vehicle for a defined shift while also accounting for breaks.

Shift start and end are hard constraints. They are defined at the vehicle level (default or individually) and will influence how unassigned penalties are applied to the value function.

JSON

{
  "defaults": {
    "vehicles": {
      // Driver shift starts at 9:00am and ends at 11:00am.
      "shift_start": "2021-10-17T09:00:00-06:00",
      "shift_end": "2021-10-17T11:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { "id": "vehicle-1" }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.8703, "lat": 33.1058 }
    },
    {
      "id": "location-2",
      "position": { "lon": -96.6154, "lat": 33.0117 }
    },
    {
      "id": "location-3",
      "position": { "lon": -96.8205, "lat": 32.7546 }
    }
  ]
}

Stop duration

Stop duration is the estimated amount of time in seconds a vehicle needs to service a stop. For example, a vehicle might need less time to service a stop for a ride-sharing scenario than it would for loading large quantities of produce in a sourcing scenario.

They are defined at the stop level (default or individually).

JSON

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-10-17T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    { "id": "vehicle-1" }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": { "lon": -96.8703, "lat": 33.1058 },
      // It takes 20 minutes to service the location.
      "stop_duration": 1200
    },
    {
      "id": "location-2",
      "position": { "lon": -96.6154, "lat": 33.0117 },
      // It takes 30 minutes to service the location.
      "stop_duration": 1800
    },
    {
      "id": "location-3",
      "position": { "lon": -96.8205, "lat": 32.7546 },
      // It takes 40 minutes to service the location.
      "stop_duration": 2400
    }
  ]
}

Stop duration multiplier

It may be the case that some vehicles within your fleet need considerably longer time to service a stop. In order to introduce this information to the model, you can use the stop_duration_multiplier at the vehicle level to increase or decrease the given service time for the stop.

JSON

{
  "defaults": {
    "vehicles": {
      "shift_start": "2021-08-24T09:00:00-06:00",
      "speed": 10
    }
  },
  "vehicles": [
    {
      "id": "vehicle-1",
      // Increase the given service time for every stop by factor 1.2 for this vehicle
      "stop_duration_multiplier": 1.2
    },
    {
      "id": "vehicle-2"
    }
  ],
  "stops": [
    {
      "id": "location-1",
      "position": {
        "lon": 7.6129,
        "lat": 51.957
      },
      "stop_duration": 900
    },
    {
      "id": "location-2",
      "position": {
        "lon": 7.6166,
        "lat": 51.9635
      },
      "stop_duration": 600
    },
    {
      "id": "location-3",
      "position": {
        "lon": 7.6258,
        "lat": 51.9624
      },
      "stop_duration": 600
    },
    {
      "id": "location-4",
      "position": {
        "lon": 7.6386,
        "lat": 51.9449
      },
      "stop_duration": 600
    },
    {
      "id": "location-5",
      "position": {
        "lon": 7.5896,
        "lat": 51.9486
      },
      "stop_duration": 900
    }
  ]
}

You will learn the basics of working with time on cloud.