Make a request with load costs

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. For more information, see the launch stage descriptions.

Make a request with load costs to have the optimizer take into consideration the load your vehicles carry between visits. The incurred cost depends on both the amount of ShipmentRoute.VehicleLoad carried and the distance or duration of the transition (using cost_per_kilometer or cost_per_traveled_hour respectively).

A minimal example request with load costs

Here's a partial example of a request with a load cost. In this example, the single vehicle can carry no more than 1000 kg of total weightKg load, which incurs 1 cost unit per kilometer when the carried weightKg load exceeds 500 kg.

  {
    "model": {
      "vehicles": [{
        "loadLimits": {
          "weightKg": {
            "maxLoad": "1000",
            "costPerKilometer": {
              "loadThreshold": "500",
              "costPerUnitAboveThreshold": 1
            }
          }
        }
      }]
    }
  }
  

The load cost calculation for this example is as follows:

cost = max(carried load - load threshold, 0) * distance * cost per unit above threshold

So if the vehicle carries a weightKg load of 600 over 10 kilometers, the calculation would be:

(600 - 500) * 10 * 1 = 1000 cost units

Load costs can be used to model a variety of concepts, such as increased vehicle energy usage when transporting heavy loads or vehicle wear incurred by excessive vehicle loading.

Another example request with load costs

Here is another example of load costs that imposes a cost per traveled time both above and below a threshold:

  {
    "model": {
      "vehicles": [{
        "loadLimits": {
          "weightLbs": {
            "maxLoad": "1000",
            "costPerTraveledHour": {
              "loadThreshold": "900",
              "costPerUnitAboveThreshold": 10,
              "costPerUnitBelowThreshold": 1
            },
          },
        }
      }]
    }
  }
  

The load cost calculation for this example is as follows:

cost = max(carried load - load threshold, 0) * time * cost per unit above threshold
  + min(carried load, load threshold) * time * cost per unit below threshold

So if the vehicle carries a weightLbs load of 950 for 5 hours, the calculation would be:

max(950 - 900, 0) * 5 * 10 + min(950, 900) * 5 * 1 = 7000

In this example, the load_threshold for the weightLbs load cost is close to max_load. The cost_per_unit_above_threshold applies a high cost per traveled hour when the vehicle travels with an especially heavy load, penalizing routes that may increase wear on the vehicle or consume excess fuel. The cost_per_unit_below_threshold adds a cost per unit weight being carried by the vehicle up to the threshold, representing increased fuel consumption as the vehicle carries more load.

Frequently asked questions

Here are some frequently asked questions about load costs:

Question	Answer
Where do I specify load costs?	Specify load costs in Vehicle.LoadLimit.
How are load costs matched with shipments?	A load cost applies to shipments whose load demand type matches the type of the load limit for the vehicle, such as weight or volume. Load types are arbitrary strings, as described in load demands and limits.
How are load costs expressed?	Load costs are expressed in terms of transition distance or duration. Use cost_per_kilometer to specify costs in terms of distance and cost_per_traveled_hour to specify costs in terms of duration.
When are load costs applied?	Vehicle load is compared with the load_threshold of the load cost. If cost_per_unit_above_threshold is specified, cost is added proportional to the vehicle's load above the load_threshold using the formula max(0, load - load_threshold). If cost_per_unit_below_threshold is specified, cost is added proportional to the vehicle's load below the load_threshold, using the formula min(load, load_threshold).
What are default values for load cost parameters?	load_threshold, cost_per_unit_above_threshold, and cost_per_unit_below_threshold are all zero by default.
In what units are load costs expressed?	Load costs are expressed in the same dimensionless units as all other cost parameters, such as global_duration_cost_per_hour or Shipment.penalty_cost.
Where do I find load costs in the response?	Incurred load costs appear in the metrics and route_metrics properties of response messages. For example, an incurred cost_per_kilometer will appear as model.vehicles.load_limits.cost_per_kilometer.

For a detailed explanation of load costs, see the reference documentation (REST, gRPC).

Example: Make an OptimizeTours Request

OptimizeTours requests can also be made using either REST or gRPC.

Before making a request, replace the following parameters with values appropriate for your environment:

• Ensure you have Application Default Credentials configured as described in Use OAuth.

• Set PROJECT_NUMBER_OR_ID to your Cloud project number or ID.

  The following command sends an OptimizeTours request to the Route Optimization API and receives a response synchronously.

  curl -X POST 'https://routeoptimization.googleapis.com/v1/projects/PROJECT_NUMBER_OR_ID:optimizeTours' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
  --data @- << EOM
  {
    "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
              }
            }
          }
        }
      ]
    }
  }
  EOM

  Note: This example uses the --data @- to read a request from standard input. Use --data @Filename to read from a file.

Once the request completes, you'll receive a response message.