> [!WARNING]
> This product or feature is Experimental (pre-GA). Pre-GA products and features might have limited support, and changes to pre-GA products and features might not be compatible with other pre-GA versions. Pre-GA Offerings are covered by the [Google
> Maps Platform Service Specific Terms](https://cloud.google.com/maps-platform/terms/maps-service-terms). For more information, see the [launch stage descriptions](https://developers.google.com/maps/launch-stages.md.txt).
Load costs specify the costs or penalties that a vehicle incurs based on the
load it carries between shipment pickups and deliveries. You can configure these
costs based on travel distance with `costPerKilometer`, travel duration with
`costPerTraveledHour`, or use both at the same time.
Configure load costs to support objectives such as the following:
- Factor in fuel costs that increase with cargo weight.
- Avoid routing heavily loaded vehicles over long distances.
- Account for vehicle wear and tear from heavy cargo.
## Properties
Specify load costs within the [`loadLimits`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Vehicle.FIELDS.load_limits) property of a [`Vehicle`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#vehicle).
Like all other cost parameters, load costs use dimensionless, relative cost
units.
You can define load costs using the following properties:
| Property | Type | Description |
|---|---|---|
| [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadLimit.FIELDS.cost_per_kilometer) | Object | Contains a [`LoadCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#loadcost) object type to calculate travel costs based on kilometers traveled. |
| [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadLimit.FIELDS.cost_per_traveled_hour) | Object | Contains a [`LoadCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#loadcost) object type to calculate travel costs based on traveled hours, excluding wait, visit, and break times. |
### LoadCost
A [`LoadCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#loadcost) message type defines the travel cost of carrying a specific
load. It lets you set a load threshold, and then specify different cost rates
per unit of load both below and above that threshold.
The [`LoadCost`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#loadcost) object contains the following configuration parameters:
| Parameter | Type | Description |
|---|---|---|
| [`loadThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.load_threshold) | string (int64 format) | The load level where the cost calculation rate changes. Default is `0`. |
| [`costPerUnitAboveThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_above_threshold) | Number | The cost applied to each unit of load above the [`loadThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.load_threshold). Default is `0`. |
| [`costPerUnitBelowThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_below_threshold) | Number | The cost applied to each unit of load below or equal to the [`loadThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.load_threshold). Default is `0`. |
### Matching load costs with shipments
Load costs apply when a vehicle's carried load matches the [`loadDemands`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#Shipment.FIELDS.load_demands)
type of the shipments on its route. Load types are arbitrary strings, such as
weight or volume. For more details on configuring load types, see [Load
types](https://developers.google.com/maps/documentation/route-optimization/concepts/load-demands-limits#load_type).
## Examples
This section covers three types of examples:
- [Code samples](https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request.md.txt#code_samples) that illustrate the structure of load costs.
- [An example scenario](https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request.md.txt#example_scenario) that shows one way to use load costs to achieve a business objective.
- [A request example](https://developers.google.com/maps/tt/route-optimization/experimental/load-cost/make-request.md.txt#request_example) that includes the values set in the example scenario.
### Code samples
The following example shows how to structure a load cost with all available
configuration parameters. This sample uses [`costPerKilometer`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadLimit.FIELDS.cost_per_kilometer), but you can
replace it with [`costPerTraveledHour`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadLimit.FIELDS.cost_per_traveled_hour) to calculate costs based on travel
duration instead of distance.
```json
{
"model": {
"vehicles": [{
"loadLimits": {
"LOAD_TYPE": {
"maxLoad": "MAX_LOAD",
"costPerKilometer": {
"loadThreshold": "LOAD_THRESHOLD",
"costPerUnitAboveThreshold": COST_ABOVE,
"costPerUnitBelowThreshold": COST_BELOW
}
}
}
}]
}
}
```
### Example scenario
This section describes a scenario where you want to optimize fuel consumption,
and the fuel consumed is proportional to the distance and the cargo weight.
Because vehicles consume more fuel when carrying heavier loads, you want to plan
routes that deliver heavier packages first.
To set up this behavior, you can configure your request to penalize vehicles
that travel long distances with heavy cargo. For this example, use the following
property values in your request:
| Parent | Property | Type | Value | Scenario |
|---|---|---|---|---|
| `loadLimits` | load type | string | `weightKg` | Defines the type of capacity to track. This example uses `weightKg` to represent cargo weight in kilograms. |
| `loadLimits` | `maxLoad` | string | `100` | The maximum cargo weight the vehicle can carry. |
| `costPerKilometer` | `loadThreshold` | string | `15` | Sets the baseline load threshold. Any cargo weight above 15 kg incurs the load-based fuel cost penalty. |
| `costPerKilometer` | `costPerUnitAboveThreshold` | number | `1` | Acts as your fuel cost coefficient. For every kilometer traveled, each kilogram of cargo over the 15 kg threshold incurs 1 cost unit. |
| `loadDemands` | `amount` | string | Shipment 1: `50` Shipment 2: `10` Shipment 3: `80` | Specifies the cargo weight for each of your three shipments. |
In this scenario, your configured values have the following effects:
- **The optimizer arranges your routes to deliver your heaviest packages
first.** The solver schedules the 80 kg and 50 kg deliveries at the beginning of the route to minimize the distance traveled while heavily loaded.
- **The optimizer arranges your routes to minimize distance traveled with heavy
cargo.** To see how these settings affect your routes, you can increase `costPerUnitAboveThreshold` from `1` to `5`. By making the weight penalty higher, you prompt the optimizer to work even harder to minimize the distance traveled with heavier cargo, which can rearrange the drop-off sequence or split the shipments across multiple vehicles.
### 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 load cost values from the example scenario:
```json
{
"model": {
"shipments": [
{
"deliveries": [
{
"arrivalLocation": {
"latitude": 37.789456,
"longitude": -122.390192
},
"duration": "250s"
}
],
"penaltyCost": 100.0,
"loadDemands": {
"weightKg": {
"amount": "50"
}
}
},
{
"deliveries": [
{
"arrivalLocation": {
"latitude": 37.789116,
"longitude": -122.395080
},
"duration": "250s"
}
],
"penaltyCost": 30.0,
"loadDemands": {
"weightKg": {
"amount": "10"
}
}
},
{
"deliveries": [
{
"arrivalLocation": {
"latitude": 37.795242,
"longitude": -122.399347
},
"duration": "250s"
}
],
"penaltyCost": 50.0,
"loadDemands": {
"weightKg": {
"amount": "80"
}
}
}
],
"vehicles": [
{
"endLocation": {
"latitude": 37.794465,
"longitude": -122.394839
},
"startLocation": {
"latitude": 37.794465,
"longitude": -122.394839
},
"costPerHour": 40.0,
"costPerKilometer": 10.0,
"loadLimits": {
"weightKg": {
"maxLoad": "100",
"costPerKilometer": {
"loadThreshold": "15",
"costPerUnitAboveThreshold": 1
}
}
}
}
]
}
}
```
## Calculation formulas
The optimizer calculates load costs using the following formulas.
### Full threshold calculation
When you specify both [`costPerUnitAboveThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_above_threshold) and
[`costPerUnitBelowThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_below_threshold), you incur separate travel costs for load
amounts both above and below the [`loadThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.load_threshold). The formula is:
cost = max(carried_load - load_threshold, 0) * distance_or_time * cost_per_unit_above_threshold
+ min(carried_load, load_threshold) * distance_or_time * cost_per_unit_below_threshold
For example, using the values from the **Request example** , where the value of
[`costPerUnitBelowThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_below_threshold) is `2`, if the vehicle travels 10 kilometers
carrying a load of 50, the calculation is:
max(50 - 15, 0) * 10 * 1 + min(50, 15) * 10 * 2 = 650 cost units
### Above-threshold calculation
When you specify only [`costPerUnitAboveThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_above_threshold), the calculation is a
special case of the full threshold formula. Because the cost below the threshold
is zero, the second half of the full formula evaluates to zero. The formula is:
cost = max(carried_load - load_threshold, 0) * distance_or_time * cost_per_unit_above_threshold
For example, using the values from the **Request example** where
[`loadThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.load_threshold) is `15` and [`costPerUnitAboveThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_above_threshold) is `1`, if
the vehicle travels 10 kilometers carrying a load of 50, the calculation is:
max(50 - 15, 0) * 10 * 1 = 350 cost units
### Below-threshold calculation
Symmetrically, if you specify only [`costPerUnitBelowThreshold`](https://developers.google.com/maps/documentation/route-optimization/reference/rest/v1/ShipmentModel.md.txt#LoadCost.FIELDS.cost_per_unit_below_threshold), the
calculation is another special case of the full threshold formula where the cost
above the threshold is zero. The formula is:
cost = min(carried_load, load_threshold) * distance_or_time * cost_per_unit_below_threshold