![Time windows are present in `ShipmentModel`, in `Shipment` in the pickups and deliveries objects, and in `Vehicle`.](https://developers.google.com/static/maps/documentation/route-optimization/images/time-windows.svg "Time windows data diagram") 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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_start_time) and [`globalEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_end_time) are properties of [`ShipmentModel`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt) - [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) are properties of: - [`pickups`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.pickups) inside [`Shipment`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment). - [`deliveries`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.deliveries) inside [`Shipment`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment). - [`startTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.start_time_windows) and [`endTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.end_time_windows) are properties of [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle). ## Essentials checklist The following checklist describes essential knowledge that prevents potential mistakes related to time windows. This list can help you validate your request and troubleshoot your response. All shipment and vehicle time windows **must fall within the [`globalStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_start_time) and [`globalEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_end_time) time window**. Shipments and vehicles time windows **must use the [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow) message type**. **The values of [`globalStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_start_time) and [`globalEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_end_time) are timestamps** , unlike other time windows which use the `TimeWindow` message type. **You can have multiple [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow) objects** for a given shipment and vehicle. **A [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle) has two types of time window properties** : [`startTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.start_time_windows) and [`endTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.end_time_windows), which define **an interval of time** where a vehicle should begin and end its routes respectively. **For shipments, [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) 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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_start_time) | [`Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The earliest time for any event. | | [`globalEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_end_time) | [`Timestamp`](https://protobuf.dev/reference/protobuf/google.protobuf/#timestamp) | The latest time for any event. | The following table describes the time window properties in shipments and vehicles. | Parent | Property | Format | Description | |---|---|---|---| | [`Shipment`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment).[`pickups`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.pickups) | [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) | Array of [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow) message types. | Specifies time intervals for a shipment pickup. | | [`Shipment`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment).[`deliveries`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.deliveries) | [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) | Array of [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow) message types. | Specifies time intervals for a shipment delivery. | | [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle) | [`startTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.start_time_windows) | Array of [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow) message types. | Specifies start time for a vehicle's operating schedule. | | [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle) | [`endTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.end_time_windows) | Array of [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow) message types. | Specifies end time for a vehicle's operating schedule. | > [!NOTE] > **Note:** Vehicle schedules can also be affected by [`BreakRule`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#breakrule)s, which define periods when vehicle operators can take breaks. For more details, see the [`BreakRule` reference > documentation](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel#breakrule). The following table describes the properties of a [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#timewindow) message type. | Property | Format | Description | |---|---|---| | [`startTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.start_time) | String (RFC3339 UTC "Zulu" format) | The start of a time window. | | [`endTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.end_time) | String (RFC3339 UTC "Zulu" format) | The end of a time window. | ## Examples This section covers three types of examples: - [**Code samples**](https://developers.google.com/maps/documentation/route-optimization/concepts/time-windows.md.txt#code_samples) that illustrate the structure of time windows. - [**An example scenario**](https://developers.google.com/maps/documentation/route-optimization/concepts/time-windows.md.txt#example_scenario) that shows one way to use time windows to achieve a business objective. - [**A request example**](https://developers.google.com/maps/documentation/route-optimization/concepts/time-windows.md.txt#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: ```json { "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: ```json { "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: ```json { "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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt) | [`globalStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_start_time) | `2023-01-13T07:00:00Z` | Represents the opening time of your doggy daycare. No pickups or deliveries can happen before this time. | | [`ShipmentModel`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt) | [`globalEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_end_time) | `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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.pickups) | [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) | `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. | | [`Shipment.pickups`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.pickups) | [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) | `endTime`: `2023-01-13T09:00: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. | | [`Shipment.deliveries`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.deliveries) | [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) | `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. | | [`Shipment.deliveries`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.deliveries) | [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) | `endTime`: `2023-01-13T18:30: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. | | [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle) | [`startTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.start_time_windows) | `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). | | [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle) | [`endTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.end_time_windows) | `startTime`: `2023-01-13T18:45:00Z` `endTime`: `2023-01-13T19:00: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). | 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.](https://developers.google.com/static/maps/documentation/route-optimization/images/time-windows-example.svg "Time windows example diagram") 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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) at the start and end of the day respectively. - The vehicle's [`startTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.start_time_windows) give the vehicle operator a timeframe in which they must start working, and [`endTimeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.end_time_windows) provide another timeframe in which they must finish their day. - The start time of the first [`startTimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.start_time_windows) and the end time of the last [`endTimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.end_time_windows) 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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/projects/optimizeTours.md.txt) request incorporating the example scenario time windows values. ```json { "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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.soft_start_time) and [`softEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.soft_end_time) in a [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_start_time) and [`globalEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#FIELDS.global_end_time) since they don't use the [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#timewindow) message type. - They are only applicable when there is a single [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#timewindow) in a list. ### Properties The following table describes the soft constraint properties for time windows. | Property name | Format | Property description | |---|---|---| | [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.soft_start_time) | Timestamp | Specifies the beginning of the soft time window. If an event occurs before this time, a cost is incurred. | | [`softEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.soft_end_time) | Timestamp | Specifies the end of the soft time window. If an event occurs after this time, a cost is incurred. | | [`costPerHourBeforeSoftStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.cost_per_hour_before_soft_start_time) | number | The cost per hour incurred when an event starts before the [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.soft_start_time). This property is required when using [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.soft_start_time). See the [Cost model](https://developers.google.com/maps/documentation/route-optimization/concepts/costs.md.txt) key concept to learn more about how to implement costs. | | [`costPerHourAfterSoftEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.cost_per_hour_after_soft_end_time) | number | The cost per hour incurred when an event ends after the [`softEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.soft_end_time). This property is required when using [`softEndTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/Shipment.TimeWindow#TimeWindow.FIELDS.soft_end_time). See the [Cost model](https://developers.google.com/maps/documentation/route-optimization/concepts/costs.md.txt) 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`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#timewindow) message type: ```json { "softStartTime": "SOFT_START_TIME", "softEndTime": "SOFT_END_TIME", "costPerHourBeforeSoftStartTime": COST_BEFORE_START_TIME, "costPerHourAfterSoftEndTime": COST_AFTER_END_TIME } ```