This example shows how to use [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows) to set pickup and delivery times for shipments. For a complete conceptual overview and to learn more ways to use [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows), see the [**Time windows key concept**](https://developers.google.com/maps/documentation/route-optimization/concepts/time-windows) document. ## Scenario 1: Delivering within time windows The following example demonstrates a scenario where a single vehicle must deliver three shipments within their specified [`timeWindows`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#VisitRequest.FIELDS.time_windows). ### Example request This request includes three shipments, each with a different delivery [`TimeWindow`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow): - `shipments[0]` delivery window: 18:00 - 19:00 - `shipments[1]` delivery window: 18:00 - 18:30 - `shipments[2]` delivery window: 17:30 - 18:00 #### See an example request with time windows ```json { "populatePolylines": false, "populateTransitionPolylines": false, "model": { "globalStartTime": "2023-01-13T16:00:00Z", "globalEndTime": "2023-01-14T16:00:00Z", "shipments": [ { "deliveries": [ { "arrivalLocation": { "latitude": 37.789456, "longitude": -122.390192 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T18:00:00Z", "endTime": "2023-01-13T19:00:00Z" } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 100.0 }, { "deliveries": [ { "arrivalLocation": { "latitude": 37.789116, "longitude": -122.395080 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T18:00:00Z", "endTime": "2023-01-13T18:30:00Z" } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 20.0 }, { "deliveries": [ { "arrivalLocation": { "latitude": 37.795242, "longitude": -122.399347 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T17:30:00Z", "endTime": "2023-01-13T18:00:00Z" } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 50.0 } ], "vehicles": [ { "endLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "startLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "costPerHour": 40.0, "costPerKilometer": 10.0 } ] } } ``` ### Example response The response shows that the optimizer schedules each of the [`visits`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentRoute.md.txt#FIELDS.visits) to respect the time windows, delivering shipments with earlier windows first. #### See a response to the example request with time windows ```json { "routes": [ { "vehicleStartTime": "2023-01-13T17:35:50Z", "vehicleEndTime": "2023-01-13T18:17:24Z", "visits": [ { "isPickup": true, "startTime": "2023-01-13T17:35:50Z", "detour": "0s" }, { "shipmentIndex": 1, "isPickup": true, "startTime": "2023-01-13T17:38:20Z", "detour": "150s" }, { "shipmentIndex": 2, "isPickup": true, "startTime": "2023-01-13T17:40:50Z", "detour": "300s" }, { "shipmentIndex": 2, "startTime": "2023-01-13T17:50:09Z", "detour": "0s" }, { "shipmentIndex": 1, "startTime": "2023-01-13T18:00:00Z", "detour": "796s" }, { "startTime": "2023-01-13T18:07:35Z", "detour": "1520s" } ], "transitions": [ { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:35:50Z" }, { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:38:20Z" }, { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:40:50Z" }, { "travelDuration": "409s", "travelDistanceMeters": 1371, "waitDuration": "0s", "totalDuration": "409s", "startTime": "2023-01-13T17:43:20Z" }, { "travelDuration": "341s", "travelDistanceMeters": 1312, "waitDuration": "0s", "totalDuration": "341s", "startTime": "2023-01-13T17:54:19Z" }, { "travelDuration": "205s", "travelDistanceMeters": 636, "waitDuration": "0s", "totalDuration": "205s", "startTime": "2023-01-13T18:04:10Z" }, { "travelDuration": "339s", "travelDistanceMeters": 1276, "waitDuration": "0s", "totalDuration": "339s", "startTime": "2023-01-13T18:11:45Z" } ], "metrics": { "performedShipmentCount": 3, "travelDuration": "1294s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "1200s", "totalDuration": "2494s", "travelDistanceMeters": 4595 }, "routeCosts": { "model.vehicles.cost_per_hour": 27.711111111111112, "model.vehicles.cost_per_kilometer": 45.95 }, "routeTotalCost": 73.661111111111111 } ], "metrics": { "aggregatedRouteMetrics": { "performedShipmentCount": 3, "travelDuration": "1294s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "1200s", "totalDuration": "2494s", "travelDistanceMeters": 4595 }, "usedVehicleCount": 1, "earliestVehicleStartTime": "2023-01-13T17:35:50Z", "latestVehicleEndTime": "2023-01-13T18:17:24Z", "totalCost": 73.661111111111111, "costs": { "model.vehicles.cost_per_hour": 27.711111111111112, "model.vehicles.cost_per_kilometer": 45.95 } } } ``` The delivery [`startTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentRoute.md.txt#Visit.FIELDS.start_time) for each shipment falls within its requested window: - `shipments[2]` is delivered at 17:50 (within its 17:30 - 18:00 window). - `shipments[1]` is delivered at 18:00 (within its 18:00 - 18:30 window). - `shipments[0]` is delivered at 18:07 (within its 18:00 - 19:00 window). ## Scenario 2: Skipping a shipment due to time windows The following example demonstrates a scenario where a shipment's time window is too far apart from the others, making it more cost-effective for the optimizer to skip the shipment and pay the [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost). ### Example request This request is the same as the first scenario, except one shipment's delivery window is at a different time, much later in the day. - `shipments[1]` delivery window is now: 21:00 - 21:30 #### See an example request with time windows that cannot be satisfied ```json { "populatePolylines": false, "populateTransitionPolylines": false, "model": { "globalStartTime": "2023-01-13T16:00:00Z", "globalEndTime": "2023-01-14T16:00:00Z", "shipments": [ { "deliveries": [ { "arrivalLocation": { "latitude": 37.789456, "longitude": -122.390192 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T18:00:00Z", "endTime": "2023-01-13T19:00:00Z" } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 100.0 }, { "deliveries": [ { "arrivalLocation": { "latitude": 37.789116, "longitude": -122.395080 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T21:00:00Z", "endTime": "2023-01-13T21:30:00Z" } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 20.0 }, { "deliveries": [ { "arrivalLocation": { "latitude": 37.795242, "longitude": -122.399347 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T17:30:00Z", "endTime": "2023-01-13T18:00:00Z" } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 50.0 } ], "vehicles": [ { "endLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "startLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "costPerHour": 40.0, "costPerKilometer": 10.0 } ] } } ``` ### Example response The response shows that the optimizer skips `shipment[1]`. This happens because, to deliver that shipment, the vehicle would have to operate for several extra hours, and the calculated cost for that time is higher than the shipment's [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) of 20.0. #### See a response to the example request with time windows where a shipment is skipped ```json { "routes": [ { "vehicleStartTime": "2023-01-13T17:37:49Z", "vehicleEndTime": "2023-01-13T18:09:49Z", "visits": [ { "isPickup": true, "startTime": "2023-01-13T17:37:49Z", "detour": "0s" }, { "shipmentIndex": 2, "isPickup": true, "startTime": "2023-01-13T17:40:19Z", "detour": "150s" }, { "shipmentIndex": 2, "startTime": "2023-01-13T17:49:38Z", "detour": "0s" }, { "startTime": "2023-01-13T18:00:00Z", "detour": "946s" } ], "transitions": [ { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:37:49Z" }, { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:40:19Z" }, { "travelDuration": "409s", "travelDistanceMeters": 1371, "waitDuration": "0s", "totalDuration": "409s", "startTime": "2023-01-13T17:42:49Z" }, { "travelDuration": "372s", "travelDistanceMeters": 1348, "waitDuration": "0s", "totalDuration": "372s", "startTime": "2023-01-13T17:53:48Z" }, { "travelDuration": "339s", "travelDistanceMeters": 1276, "waitDuration": "0s", "totalDuration": "339s", "startTime": "2023-01-13T18:04:10Z" } ], "metrics": { "performedShipmentCount": 2, "travelDuration": "1120s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "800s", "totalDuration": "1920s", "travelDistanceMeters": 3995 }, "routeCosts": { "model.vehicles.cost_per_kilometer": 39.95, "model.vehicles.cost_per_hour": 21.333333333333332 }, "routeTotalCost": 61.283333333333331 } ], "skippedShipments": [ { "index": 1 } ], "metrics": { "aggregatedRouteMetrics": { "performedShipmentCount": 2, "travelDuration": "1120s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "800s", "totalDuration": "1920s", "travelDistanceMeters": 3995 }, "usedVehicleCount": 1, "earliestVehicleStartTime": "2023-01-13T17:37:49Z", "latestVehicleEndTime": "2023-01-13T18:09:49Z", "totalCost": 81.283333333333331, "costs": { "model.shipments.penalty_cost": 20, "model.vehicles.cost_per_hour": 21.333333333333332, "model.vehicles.cost_per_kilometer": 39.95 } } } ``` The [`skippedShipments`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt#FIELDS.skipped_shipments) array in the response shows that the shipment with `index: 1` was not performed. which affects the following cost parameters: - The [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) of 20.0 from that shipment is included in the [`metrics.costs`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt#Metrics.FIELDS.costs). - The [`totalCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt#Metrics.FIELDS.total_cost) (81.28) is the sum of the [`routeTotalCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentRoute.md.txt#FIELDS.route_total_cost) (61.28) and the `penalty_cost` (20.0). ## Scenario 3: Using soft time windows The following example shows how to use a soft time window, which allows the optimizer to schedule a delivery outside of the specified time range, but at a cost. For a conceptual overview of this feature, see the [soft time windows](https://developers.google.com/maps/documentation/route-optimization/concepts/time-windows#soft_time_windows) section in the Time Windows key concepts document. ### Example request This request modifies the previous scenario by changing the hard time window for `shipment[1]` to a soft one. This is done by using [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.soft_start_time) and providing a [`costPerHourBeforeSoftStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.cost_per_hour_before_soft_start_time). `shipment[1]` now has a [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.soft_start_time) of 21:00 and a [`costPerHourBeforeSoftStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.cost_per_hour_before_soft_start_time) of 2.0. This means a penalty is applied for every hour the delivery is made *before* 21:00. #### See an example request with hard and soft time windows ```json { "populatePolylines": false, "populateTransitionPolylines": false, "model": { "globalStartTime": "2023-01-13T16:00:00Z", "globalEndTime": "2023-01-14T16:00:00Z", "shipments": [ { "deliveries": [ { "arrivalLocation": { "latitude": 37.789456, "longitude": -122.390192 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T18:00:00Z", "softEndTime": "2023-01-13T19:00:00Z", "costPerHourAfterSoftEndTime": 2.0 } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 100.0 }, { "deliveries": [ { "arrivalLocation": { "latitude": 37.789116, "longitude": -122.395080 }, "duration": "250s", "timeWindows": [ { "softStartTime": "2023-01-13T21:00:00Z", "endTime": "2023-01-13T21:30:00Z", "costPerHourBeforeSoftStartTime": 2.0 } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 20.0 }, { "deliveries": [ { "arrivalLocation": { "latitude": 37.795242, "longitude": -122.399347 }, "duration": "250s", "timeWindows": [ { "startTime": "2023-01-13T17:30:00Z", "softEndTime": "2023-01-13T18:00:00Z", "costPerHourAfterSoftEndTime": 2.0 } ] } ], "pickups": [ { "arrivalLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "duration": "150s" } ], "penaltyCost": 50.0 } ], "vehicles": [ { "endLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "startLocation": { "latitude": 37.794465, "longitude": -122.394839 }, "costPerHour": 40.0, "costPerKilometer": 10.0 } ] } } ``` ### Example response The response shows that the optimizer now schedules all three shipments. It schedules the delivery of `shipment[1]` significantly earlier than its 21:00 [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.soft_start_time). This is the most cost-effective solution since the cost of violating the soft time window is less than the [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) of skipping the shipment, and it's also lower than the cost of having a vehicle wait to deliver during the time window. #### See a response to the example request with hard and soft time windows ```json { "routes": [ { "vehicleStartTime": "2023-01-13T17:48:35Z", "vehicleEndTime": "2023-01-13T18:24:28Z", "visits": [ { "isPickup": true, "startTime": "2023-01-13T17:48:35Z", "detour": "0s" }, { "shipmentIndex": 1, "isPickup": true, "startTime": "2023-01-13T17:51:05Z", "detour": "150s" }, { "shipmentIndex": 2, "isPickup": true, "startTime": "2023-01-13T17:53:35Z", "detour": "300s" }, { "startTime": "2023-01-13T18:00:00Z", "detour": "300s" }, { "shipmentIndex": 1, "startTime": "2023-01-13T18:07:42Z", "detour": "493s" }, { "shipmentIndex": 2, "startTime": "2023-01-13T18:17:27Z", "detour": "873s" } ], "transitions": [ { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:48:35Z" }, { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:51:05Z" }, { "travelDuration": "0s", "waitDuration": "0s", "totalDuration": "0s", "startTime": "2023-01-13T17:53:35Z" }, { "travelDuration": "235s", "travelDistanceMeters": 795, "waitDuration": "0s", "totalDuration": "235s", "startTime": "2023-01-13T17:56:05Z" }, { "travelDuration": "212s", "travelDistanceMeters": 791, "waitDuration": "0s", "totalDuration": "212s", "startTime": "2023-01-13T18:04:10Z" }, { "travelDuration": "335s", "travelDistanceMeters": 1204, "waitDuration": "0s", "totalDuration": "335s", "startTime": "2023-01-13T18:11:52Z" }, { "travelDuration": "171s", "travelDistanceMeters": 665, "waitDuration": "0s", "totalDuration": "171s", "startTime": "2023-01-13T18:21:37Z" } ], "metrics": { "performedShipmentCount": 3, "travelDuration": "953s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "1200s", "totalDuration": "2153s", "travelDistanceMeters": 3455 }, "routeCosts": { "model.shipments.deliveries.time_windows.cost_per_hour_after_soft_end_time": 0.58166666666666667, "model.shipments.deliveries.time_windows.cost_per_hour_before_soft_start_time": 5.7433333333333332, "model.vehicles.cost_per_hour": 23.922222222222221, "model.vehicles.cost_per_kilometer": 34.55 }, "routeTotalCost": 64.797222222222217 } ], "metrics": { "aggregatedRouteMetrics": { "performedShipmentCount": 3, "travelDuration": "953s", "waitDuration": "0s", "delayDuration": "0s", "breakDuration": "0s", "visitDuration": "1200s", "totalDuration": "2153s", "travelDistanceMeters": 3455 }, "usedVehicleCount": 1, "earliestVehicleStartTime": "2023-01-13T17:48:35Z", "latestVehicleEndTime": "2023-01-13T18:24:28Z", "totalCost": 64.797222222222217, "costs": { "model.vehicles.cost_per_kilometer": 34.55, "model.shipments.deliveries.time_windows.cost_per_hour_before_soft_start_time": 5.7433333333333332, "model.shipments.deliveries.time_windows.cost_per_hour_after_soft_end_time": 0.58166666666666667, "model.vehicles.cost_per_hour": 23.922222222222221 } } } ``` The soft time window results in a better solution, which is reflected in the following improvements: - All 3 shipments are scheduled without skipping any of them. - The [`totalCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt#Metrics.FIELDS.total_cost) is now 64.79, which is lower than the previous solution's cost of 81.28. - The [`routeCosts`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentRoute.md.txt#FIELDS.route_costs) object includes a cost of 5.74 for delivering `shipment[1]` almost 3 hours before its [`softStartTime`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#TimeWindow.FIELDS.soft_start_time). This cost is lower than the [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) of 20.0, making it the most cost-effective option.