Time windows

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 deliveries within specified timeframes.
• Plan routes to operate within overall business hours.
• Ensure vehicles start and end routes within 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

Properties

The following table describes the global time window properties.

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

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

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:

The following diagram illustrates the time windows affecting this route.

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.

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
    }