How to track weight change on waypoints
You can specify how the weight of the vehicle changes on subsequent intermediate waypoints of the calculated route using the currentWeightChange parameter in the via option.
Adding this information to the route calculation request allows the API to adjust the route with regard to road access and violation handling, and influences the consumption estimates.
This can be especially helpful for delivery companies with fleets of drivers that pick up and load in cargo on their routes. As the weight of the vehicles changes with every stop, they could gain or lose access to certain roads, can go slower or faster on certain roads, and have increased or decreased range.
Usage
To add weight change information to your route calculation request, you must add at least one intermediate waypoint.
Additionally, the request must include the vehicle[currentWeight] parameter, which is used by the API as the starting point of all weight change calculation.
To define how the weight of the vehicle changes when this waypoint is reached, add !currentWeightChange=VALUE to the waypoint coordinates.
The weight change can be a positive or negative value expressed in kilograms. This value is added to the value of the vehicle[currentWeight] parameter that is in effect when the vehicle reaches the waypoint.
For example, to add an intermediate waypoint in the Warsaw city center where a load that weighs 1 t (1000 kg) is unloaded, add this code to your route calculation request:
via=52.2136,21.0232!currentWeightChange=-1000
Negative weight handling
When a weight change on an intermediate waypoint results in a negative value of vehicle[currentWeight] parameter, the API returns a critical notice in the response.
The route is calculated for every section where adding currentWeightChange results in a negative value of vehicle[currentWeight], but the API uses vehicle[currentWeight]=0.
Weight limits
If the maximum weight limit for the selected transport mode is exceeded after adding the value defined in the currentWeightChange parameter, the API returns a critical notice and calculates the route using the maximum allowed vehicle[currentWeight] value for the transport mode.
Invalid weight validation
The system doesn't validate other potentially invalid values, such as vehicle[currentWeight] of 1 kg or when vehicle[currentWeight] is double the value of vehicle[grossWeight].
Example
The following request calculates a route with two waypoints for a truck. At the beginning the truck weighs 5000 kg. A load of 3000 kg is added at the first waypoint and 4000 kg is unloaded at the second waypoint.
curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.535153,13.269925&'\
'destination=52.535153,13.269925&'\
'via=52.529435,13.297411!currentWeightChange=+3000&'\
'via=52.517161,13.317204!currentWeightChange=-4000&'\
'return=summary&'\
'transportMode=truck&'\
'vehicle[grossWeight]=10000&'\
'vehicle[currentWeight]=5000&'\
'apiKey=YOUR_API_KEY'Response information
The weight used in each route section is returned in the response. The transport.currentWeight field shows the effective weight for each section:
{
"routes": [
{
"id": "36110c03-3b74-4698-bcec-0b75edf865b1",
"sections": [
{
"id": "29598024-11ba-44ec-9428-0fe7e72f06fd",
"type": "vehicle",
"departure": {
"time": "2025-10-29T11:10:46+01:00",
"place": {
"type": "place",
"location": {"lat": 52.5351699, "lng": 13.26993},
...
}
},
"arrival": {
"time": "2025-10-29T11:19:52+01:00",
"place": {
"type": "place",
"location": {"lat": 52.5294482, "lng": 13.2974065},
...
}
},
"summary": {"duration": 546, "length": 2514, "baseDuration": 278},
"transport": {"mode": "truck", "currentWeight": 5000}
},
{
"id": "b774ed30-c109-44c9-8d9d-134e9e0297f9",
"type": "vehicle",
...,
"transport": {"mode": "truck", "currentWeight": 8000}
},
{
"id": "98a2d99d-e09a-44c0-8508-fe5ea8323109",
"type": "vehicle",
...,
"transport": {"mode": "truck", "currentWeight": 4000}
}
]
}
]
}Impact on EV consumption
Weight change on waypoints affects EV consumption only when using the physical consumption model. The energy consumption changes for the sections affected by the weight change.
Changes in consumption affect the vehicle range. This in turn has impact on the charging stops added automatically to the route when using the ev[makeReachable] option.
Usage with route handle
Update the vehicle[currentWeight] parameter when resuming navigation after reaching waypoints with weight changes.
Example
First, request a route with weight changes on waypoints:
curl -gX GET 'https://router.hereapi.com/v8/routes?'\
'origin=52.535153,13.269925&'\
'destination=52.535153,13.269925&'\
'via=52.529435,13.297411!currentWeightChange=+3000&'\
'via=52.517161,13.317204!currentWeightChange=-4000&'\
'return=summary,routeHandle&'\
'transportMode=truck&'\
'vehicle[grossWeight]=10000&'\
'vehicle[currentWeight]=5000&'\
'apiKey=YOUR_API_KEY'When you resume navigation after the vehicle reaches the first waypoint and picks up cargo, update the vehicle[currentWeight] value to reflect the new weight:
curl -gX GET 'https://router.hereapi.com/v8/routes/{ROUTE_HANDLE}?'\
'origin=52.528672,13.300004&'\
'return=summary&'\
'rerouting[mode]=returnToRoute&'\
'rerouting[lastTraveledSectionIndex]=1&'\
'transportMode=truck&'\
'vehicle[grossWeight]=10000&'\
'vehicle[currentWeight]=8000&'\
'apiKey=YOUR_API_KEY'Note that the vehicle[currentWeight] is now set to 8000 kg, which is the weight of the vehicle after adding the weight of the cargo from the first stop. The route handle stores the weight change values for the remaining waypoints, so the weight change of -4000 kg on the next waypoint will be applied.
Related content
Updated 18 days ago