Time windows

Time windows are present in `ShipmentModel`, in `Shipment` in the pickups and deliveries objects, and in `Vehicle`.

Time windows specify the timing for events on a route. These events can include the start and end of a driver's route, scheduled pickup and delivery times, or the duration of an entire route.

Time windows can support objectives like:

Prioritize completing pickups and deliverieswithin specified timeframes.
Plan routesto operate within overall business hours.
Ensure vehicles start and end routeswithin specified timeframes.

Structure

As shown in the diagram, time windows are structured as follows:

globalStartTime and globalEndTime are properties of ShipmentModel
timeWindows are properties of:
- pickups inside Shipment .
- deliveries inside Shipment .
startTimeWindows and endTimeWindows are properties of Vehicle .

Essentials checklist

All shipment and vehicle time windows must fall within the globalStartTime and globalEndTime time window .

Shipments and vehicles time windows must use the TimeWindow message type .

The values of globalStartTime and globalEndTime are timestamps , unlike other time windows which use the TimeWindow message type.

You can have multiple TimeWindow objects for a given shipment and vehicle.

A Vehicle has two types of time window properties : startTimeWindows and endTimeWindows , which define an interval of time where a vehicle should begin and end its routes respectively.

For shipments, timeWindows apply to the start time of a pickup or delivery only . The duration of a visit can extend beyond its time window, but must fit within the vehicle's operating hours and the global time window.

Properties

The following table describes the global time window properties.

Property	Format	Description
`globalStartTime`	`Timestamp`	The earliest time for any event.
`globalEndTime`	`Timestamp`	The latest time for any event.

The following table describes the time window properties in shipments and vehicles.

Parent

Property

Format

Description

Shipment.pickups

timeWindows

Array of TimeWindow message types.

Specifies time intervals for a shipment pickup.

Shipment.deliveries

timeWindows

Specifies time intervals for a shipment delivery.

Vehicle

startTimeWindows

Specifies start time for a vehicle's operating schedule.

endTimeWindows

Specifies end time for a vehicle's operating schedule.

The following table describes the properties of a TimeWindow message type.

Property	Format	Description
`startTime`	String (RFC3339 UTC "Zulu" format)	The start of a time window.
`endTime`	String (RFC3339 UTC "Zulu" format)	The end of a time window.

Examples

This section covers three types of examples:

Code samples that illustrate the structure of time windows.
An example scenario that shows one way to use time windows to achieve a business objective.
A request example that includes the values set in the example scenario.

Code samples

The following sections show code samples of different types of time windows.

Global time windows

The following code sample shows the structure of the global time windows:

 { 
  
 "model" 
 : 
  
 { 
  
  "globalStartTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
 
 , 
  
  "globalEndTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
 
 , 
  
 "shipments" 
 : 
  
 [ 
  
 ... 
  
 ], 
  
 "vehicles" 
 : 
  
 [ 
  
 ... 
  
 ] 
  
 } 
 }

Pickups and deliveries time windows

The following code sample shows the structure of the time windows in a shipment's pickups and deliveries:

 { 
  
 "model" 
 : 
  
 { 
  
 "shipments" 
 : 
  
 [ 
  
 { 
  
 "pickups" 
 : 
  
 [ 
  
 { 
  
  "timeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
 , 
  
 "endTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
  
 } 
  
 ] 
 
  
 } 
  
 ], 
  
 "deliveries" 
 : 
  
 [ 
  
 { 
  
  "timeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
 , 
  
 "endTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
  
 } 
  
 ] 
 
  
 } 
  
 ] 
  
 } 
  
 ], 
  
 "vehicles" 
 : 
  
 [ 
  
 ... 
  
 ] 
  
 } 
 }

Vehicle time windows

The following code sample shows the structure of the time windows of a vehicle:

 { 
  
 "model" 
 : 
  
 { 
  
 "shipments" 
 : 
  
 [ 
  
 ... 
  
 ], 
  
 "vehicles" 
 : 
  
 [ 
  
 { 
  
  "startTimeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
 , 
  
 "endTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
  
 } 
  
 ], 
  
 "endTimeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
 , 
  
 "endTime" 
 : 
  
 " YYYY-MM-DDTHH:MM:SSZ 
" 
  
 } 
  
 ] 
 
  
 } 
  
 ] 
  
 } 
 }

Example scenario

This section uses a doggie daycare business scenario. The example optimizes routes for picking up and dropping off dogs from two different homes, and the owners have the same pickup and drop-off time windows. The optimizer should respect the daycare's operating hours, the specific pickup and drop-off windows for customers, and the working hours of the driver.

For this example, the property values in the request are the following:

Parent

Property

Value

Scenario

ShipmentModel

globalStartTime

2023-01-13T07:00:00Z

Represents the opening time of your doggy daycare. No pickups or deliveries can happen before this time.

ShipmentModel

globalEndTime

2023-01-13T19:00:00Z

Represents the closing time of your doggy daycare. All pickups and deliveries must be completed by this time.

Shipment.pickups

timeWindows

startTime :
2023-01-13T07:30:00Z

Defines the acceptable window for picking up a dog from a customer's home. In this example, you told both customers to be available for pickup between 7:30 AM and 9:00 AM.

endTime :
2023-01-13T09:00:00Z

Shipment.deliveries

timeWindows

startTime :
2023-01-13T17:00:00Z

Defines the acceptable window for dropping off a dog at a customer's home. In this example, you told both customers their dogs will be dropped off between 5:00 PM and 6:30 PM.

endTime :
2023-01-13T18:30:00Z

Vehicle

startTimeWindows

startTime :
2023-01-13T07:00:00Z
endTime :
2023-01-13T07:15:00Z

Defines the acceptable window for the vehicle to start (7:00 AM to 7:15 AM) and end (5:00 PM to 5:15 PM).

endTimeWindows

startTime :
2023-01-13T18:45:00Z
endTime :
2023-01-13T19:00:00Z

The following diagram illustrates the time windows affecting this route.

Several timelines represent the global time window, pickup and delivery time windows, vehicle start and end time windows, and vehicle working hours.

In this scenario, as illustrated by the diagram, the time windows work as follows:

The global time window represents the doggy daycare business hours, and all other time windows must fall inside this time window.
Pickups and deliveries have their own timeWindows at the start and end of the day respectively.
The vehicle's startTimeWindows give the vehicle operator a timeframe in which they must start working, and endTimeWindows provide another timeframe in which they must finish their day.
The start time of the first startTimeWindow and the end time of the last endTimeWindow define the vehicle's operating hours, which in this case, are the same as the global time window.

Request example

The following example shows the structure of an optimizeTours request incorporating the example scenario time windows values.

 { 
  
 "model" 
 : 
  
 { 
  
 "globalStartTime" 
 : 
  
 "2023-01-13T07:00:00Z" 
 , 
  
 "globalEndTime" 
 : 
  
 "2023-01-13T19:00:00Z" 
 , 
  
 "shipments" 
 : 
  
 [ 
  
 { 
  
 "pickups" 
 : 
  
 [ 
  
 { 
  
 "arrivalLocation" 
 : 
  
 { 
  
 "latitude" 
 : 
  
 37.8024 
 , 
  
 "longitude" 
 : 
  
 -122.4058 
  
 }, 
  
  "timeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 "2023-01-13T07:30:00Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-01-13T09:00:00Z" 
  
 } 
  
 ] 
 
  
 } 
  
 ], 
  
 "deliveries" 
 : 
  
 [ 
  
 { 
  
 "arrivalLocation" 
 : 
  
 { 
  
 "latitude" 
 : 
  
 37.759773 
 , 
  
 "longitude" 
 : 
  
 -122.427063 
  
 }, 
  
  "timeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 "2023-01-13T17:00:00Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-01-13T18:30:00Z" 
  
 } 
  
 ] 
 
  
 } 
  
 ] 
  
 }, 
  
 { 
  
 "pickups" 
 : 
  
 [ 
  
 { 
  
 "arrivalLocation" 
 : 
  
 { 
  
 "latitude" 
 : 
  
 37.7359 
 , 
  
 "longitude" 
 : 
  
 -122.5011 
  
 }, 
  
  "timeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 "2023-01-13T07:30:00Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-01-13T09:00:00Z" 
  
 } 
  
 ] 
 
  
 } 
  
 ], 
  
 "deliveries" 
 : 
  
 [ 
  
 { 
  
 "arrivalLocation" 
 : 
  
 { 
  
 "latitude" 
 : 
  
 37.759773 
 , 
  
 "longitude" 
 : 
  
 -122.427063 
  
 }, 
  
  "timeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 "2023-01-13T17:00:00Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-01-13T18:30:00Z" 
  
 } 
  
 ] 
 
  
 } 
  
 ] 
  
 } 
  
 ], 
  
 "vehicles" 
 : 
  
 [ 
  
 { 
  
 "startLocation" 
 : 
  
 { 
  
 "latitude" 
 : 
  
 37.759773 
 , 
  
 "longitude" 
 : 
  
 -122.427063 
  
 }, 
  
 "endLocation" 
 : 
  
 { 
  
 "latitude" 
 : 
  
 37.759773 
 , 
  
 "longitude" 
 : 
  
 -122.427063 
  
 }, 
  
 "costPerHour" 
 : 
  
 27 
 , 
  
  "startTimeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 "2023-01-13T07:00:00Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-01-13T07:15:00Z" 
  
 } 
  
 ] 
 
,  
  "endTimeWindows" 
 : 
  
 [ 
  
 { 
  
 "startTime" 
 : 
  
 "2023-01-13T18:45:00Z" 
 , 
  
 "endTime" 
 : 
  
 "2023-01-13T19:00:00Z" 
  
 } 
  
 ] 
 
  
 } 
  
 ] 
  
 } 
 }

Soft time windows

Time windows can be used as soft constraints by defining softStartTime and softEndTime in a TimeWindow message type. This allows the optimizer to deviate from the specified time window at a specified cost, prioritizing overall optimization over strict adherence to the timeframes when beneficial.

Soft time windows have the following usage limitations:

They can't be applied to globalStartTime and globalEndTime since they don't use the TimeWindow message type.
They are only applicable when there is a single TimeWindow in a list.

Properties

he following table describes the soft constraint properties for time windows.

Property name	Format	Property description
`softStartTime`	Timestamp	Specifies the beginning of the soft time window. If an event occurs before this time, a cost is incurred.
`softEndTime`	Timestamp	Specifies the end of the soft time window. If an event occurs after this time, a cost is incurred.
`costPerHourBeforeSoftStartTime`	number	The cost per hour incurred when an event starts before the `softStartTime` . This property is required when using `softStartTime` . See the Cost model key concept to learn more about how to implement costs.
`costPerHourAfterSoftEndTime`	number	The cost per hour incurred when an event ends after the `softEndTime` . This property is required when using `softEndTime` . See the Cost model key concept to learn more about how to implement costs.

Code sample

The following example shows the structure of the soft constraint properties of a TimeWindow message type:

  
 { 
  
 "softStartTime" 
 : 
  
 " SOFT_START_TIME 
" 
 , 
  
 "softEndTime" 
 : 
  
 " SOFT_END_TIME 
" 
 , 
  
 "costPerHourBeforeSoftStartTime" 
 : 
  
  COST_BEFORE_START_TIME 
 
 , 
  
 "costPerHourAfterSoftEndTime" 
 : 
  
  COST_AFTER_END_TIME 
 
  
 }

Time windows Stay organized with collections Save and categorize content based on your preferences.

Structure

Essentials checklist

Properties

Examples

Code samples

Global time windows

Pickups and deliveries time windows

Vehicle time windows

Example scenario

Request example

Soft time windows

Properties

Code sample

Time windows