![The cost properties are defined under ShipmentModel.shipments.Shipment and ShipmentModel.vehicles.Vehicle](https://developers.google.com/static/maps/documentation/route-optimization/images/costs.svg "Cost model diagram") The main goal of Route Optimization API is to find routes with the lowest cost. As such, the cost model is the main driver for route optimization. The cost model is a set of properties that specify global, vehicle, and shipment costs. Cost model properties support the following kinds of optimization objectives: - Efficient vehicle assignments and routes - Cost-effective pickup and delivery times - Prioritization of critical shipments ## Structure As shown in the diagram, cost model properties are structured as follows: - [`Shipment`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment) contains the [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) property. - [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle) contains the following properties: - [`fixedCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.fixed_cost) - [`costPerHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_hour) - [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_kilometer) - [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_traveled_hour) This document **only highlights essential cost model parameters**. See the reference documentation for the complete set of cost parameters.
## Essentials checklist The following checklist describes **essential knowledge** that prevents potential cost-related mistakes. This list can help you validate your request and troubleshoot your response. **Costs are required for optimization**. A request with no costs will cause the API to return nonsensical routes with long transit. **You must specify at least one of** [`costPerHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_hour), [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_kilometer), or [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_traveled_hour) per vehicle. **You can use multiple cost properties per request** to achieve more sophisticated optimization objectives. **Cost properties are not tied to a particular currency.** **You decide the value a cost unit represents**, and this value applies to all cost properties in the request. ## Properties The following table lists and describes the cost model properties. | Parent | Property name | Property type | Cost per | Property description | |---|---|---|---|---| | `Shipment` | [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) | number | Skipped shipment | The cost incurred by **skipping the shipment** . The API skips a shipment when the cost to complete it exceeds its penalty cost. - Setting [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) prioritizes the delivery of shipments with higher cost. - Not setting a shipment [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) makes the shipment **mandatory**. - Explicitly setting a shipment [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) to zero causes the API to **always skip the shipment** unless required by other constraints. | | `Vehicle` | [`fixedCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.fixed_cost) | number | Shipment | Fixed cost applied if this vehicle is used to handle a shipment. | | `Vehicle` | [`costPerHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_hour) | number | Hour | The cost of **operating a vehicle per hour** inclusive of transit, wait, visit, and break times. As this cost increases, the optimizer attempts to find faster routes that may not be the shortest routes. This property can be an effective standalone cost per vehicle due to its simplicity and completeness. | | `Vehicle` | [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_kilometer) | number | Kilometer | The cost **per kilometer traveled** by the vehicle, which can represent fuel costs or amortized vehicle maintenance costs. | | `Vehicle` | [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_traveled_hour) | number | Hour | The cost of **operating a vehicle per hour only while in transit**, excluding wait, visit, and break times. This prioritizes faster travel routes over shorter routes. | ## Examples This section covers three types of examples: - [**Code samples**](https://developers.google.com/maps/documentation/route-optimization/concepts/costs.md.txt#code_samples) that illustrate the structure of cost model properties. - [**An example scenario**](https://developers.google.com/maps/documentation/route-optimization/concepts/costs.md.txt#example_scenario) that shows one way to use cost model properties to achieve a business objective. - [**A request example**](https://developers.google.com/maps/documentation/route-optimization/concepts/costs.md.txt#request_example) that includes the values set in the example scenario. ### Code samples The following code sample shows the structure of the cost model properties in [`Shipment`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment): ```json { "model": { "shipments": [ ... { "penaltyCost": PENALTY_COST } ], "vehicles": [ ... ] } } ``` The following code sample shows the structure of the cost model properties in [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle): ```json { "model": { "shipments": [ ... ], "vehicles": [ ... { "fixedCost": FIXED_COST, "costPerKilometer": KILOMETER_COST, "costPerHour": HOUR_COST, "costPerTraveledHour": TRAVELED_HOUR_COST } ] } } ``` ### Example scenario This section describes a scenario where you have a doggy daycare business. You are optimizing a route for the truck you use to pick up the dogs from their homes. In this scenario, you want the optimizer to take in account costs related to picking up the dogs and vehicle operations when providing a route. For this example, one cost unit represents 1 dollar. This means the cost model property values in your request are the following: | Property | Value | Scenario | |---|---|---| | [`penaltyCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.penalty_cost) | 10 | Represents the penalty you offer to your customers for not picking up their dog on a scheduled day. Whenever you don't pickup the dog on a scheduled day, the customer gets 40 dollars discounted from their service total. | | [`fixedCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.fixed_cost) | 30 | Represents the daily cost of your vehicle loan payments, which is 30 dollars per day. | | [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_kilometer) | 0.08 | Represents how much gasoline your vehicle spends per kilometer. Your vehicle needs 0.04 gallons per kilometer to move, and the cost per gallon in your region is 2 dollars. | | [`costPerHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_hour) | 27 | Represents how much you pay a driver for driving your vehicle. You pay the driver 27 dollars per hour. | | [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_traveled_hour) | 2.5 | Represents how much you have to pay for the vehicle's air conditioning per hour for the dogs while on the road. Whenever the vehicle is not moving, the driver can open the doors at the back and turn off the air conditioning. | Based on costs parameters, the optimizer could make trade-offs that are not obvious to the user, but can be found through optimization. The following diagram illustrates an example where the optimizer could choose a longer but faster route through the green dashed line to avoid traffic on the dotted red line. ![The vehicle has two possible routes, one represented by a green dashed line, which is longer but doesn't have any incidents, and one represented by a red dotted line, which is shorter but has a car crash in the middle of it.](https://developers.google.com/static/maps/documentation/route-optimization/images/costs-example.png "Costs example diagram") In this scenario, the cost balance of the two routes are the following: - The green dashed line has a low [`costPerHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_hour) and [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_traveled_hour) since it's a fast route avoiding traffic, which is **more cost-effective** even when the [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_kilometer) is high. - The red dotted line has a low [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_kilometer) since it's a direct route, but the [`costPerHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_hour) and [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.cost_per_traveled_hour) are too high due to the wait-times in traffic, making it **the most expensive route**. In addition to providing cost-effective routes, the optimizer also provides a summation of the total costs of the delivery routes in the [response properties](https://developers.google.com/maps/documentation/route-optimization/concepts/costs#response_properties). ### Request example The following example shows the structure of a basic [`optimizeTours`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/projects/optimizeTours.md.txt) request incorporating the values set in the example scenario: ```json { "model": { "shipments": [ { "pickups": [ { "arrivalLocation": { "latitude": 37.8024, "longitude": -122.4058 } } ], "deliveries": [ { "arrivalLocation": { "latitude": 37.759773, "longitude": -122.427063 } } ] "penaltyCost": 40 } ], "vehicles": [ { "startLocation": { "latitude": 37.759773, "longitude": -122.427063 }, "endLocation": { "latitude": 37.759773, "longitude": -122.427063 }, "fixedCost": 30, "costPerKilometer": 0.08, "costPerHour": 27, "costPerTraveledHour": 2.5 } ] } } ``` ## Response properties The [`OptimizeToursResponse`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt) message has cost properties that describe the costs incurred in the process of completing a route: - [`metrics.costs`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt#Metrics.FIELDS.costs): The total cost across all routes broken down by cost-related request fields. - [`metrics.totalCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/OptimizeToursResponse.md.txt#Metrics.FIELDS.total_cost): The total cost across all routes summed up.