Penalties provide fine-grained control over route calculation by making certain road types more or less attractive. While the Avoid feature offers a simple on/off mechanism for toll, ferries, rail shuttles and highways, penalties allow you to specify exactly how strongly a road type should be preferred or avoided — up to and including completely blocking it.
This parameter is only available through the POST operation calculateRoutePost, as part of the routeOptions object in the request body.
Important note
Use these parameters carefully. Similar to timePreferenceOverDistance, aggressive penalty values can lead to routes that appear unusual or impractical — for example, routes through residential areas, unnecessary detours, or roads that are not suitable for the vehicle. The predefined profiles already provide well-balanced default values for typical use cases. Penalties should only be adjusted when the default behavior does not meet specific requirements.
Value ranges
Penalty values range from -99 to 2501 and control how the routing algorithm treats specific roads. A penalty increases the internal cost of using a road, making it less likely to be chosen. A negative value decreases the cost, making the road more attractive.
- -99 to -1: Preference — Makes the road more attractive. A value of -99 reduces the cost to nearly zero, strongly favoring the road.
- 0: No effect — The road is treated normally.
- 1 to 100: Mild avoidance — The road becomes less attractive. A value of 100 doubles the cost of using the road.
- 101 to 2500: Strong avoidance — The road becomes significantly less attractive. Higher values make it increasingly unlikely the road will be used.
- 2501: Blocked — The road is prohibited.
In practice, the most common values are 0 (no change), 2500 (avoid if there is no alternative), 2501 (blocked), and values in the range of 1 to 100 for moderate avoidance. Values above 100 are rarely needed.
Penalty types
byRoadCategory
An array of 8 penalty values, one per road category. The first element represents motorways, the last one pedestrian and cycle paths.
This is useful when you want more control over route guidance than the predefined routing modes provide. Typical use cases:
- Prefer main roads: Increase penalties for lower road categories (elements 5–8) to guide routes onto larger roads. This is useful for heavy goods vehicles that should stay on trunk roads and avoid narrow residential streets.
- Prefer smaller roads: Decrease penalties for lower categories or increase penalties for highways (elements 1–2). This is relevant for agricultural vehicles or local delivery that prefer smaller, direct roads and want to avoid motorways.
- Mixed scenarios: For example, a value like [0,0,15,35,100,255,1000,1000] mildly avoids smaller roads while keeping motorways fully available.
deliveryOnly
Penalty for roads restricted to delivery vehicles only. This value is 2500 to allow entering or exiting delivery-only zones but to avoid through traffic. Using 0 or a very low value will allow transit through delivery-only zones which may be unwanted. The blocking penalty of 2501 is not supported.
residentsOnly
Penalty for roads restricted to residents only. These roads are typically in residential areas where through-traffic is not permitted. This value is usually 2500 to allow entering or exiting residents-only zones but to avoid through traffic. Using 0 or a very low value will allow transit through residents-only zones which may be unwanted. With the blocking penalty of 2501, residents-only roads will only be used if there is absolutely no alternative (e.g., two waypoints are in isolated network areas, or a waypoint is located directly on the blocked road).
toll
Penalty for toll roads. This provides more control than options[avoid]=TOLL — instead of a binary avoid, you can specify how strongly toll roads should be discouraged, or block them entirely with 2501. Cannot be used together with options[avoid]=TOLL.
ferries
Penalty for ferries. Allows you to fine-tune how strongly ferries should be avoided rather than a binary on/off. Cannot be used together with options[avoid]=FERRIES.
railShuttles
Penalty for rail shuttles (e.g., the Channel Tunnel shuttle). Cannot be used together with options[avoid]=RAIL_SHUTTLES.
Delivery-only gates
The parameter allowDeliveryOnlyGates controls whether gates that restrict access to delivery-only zones may be passed during route calculation. A delivery-only gate is a specific point in the road network where passage is normally prohibited unless the vehicle is authorized for delivery.
Set this parameter to true if your vehicle is authorized to pass through these gates. By default, delivery-only gates are treated as blocked.
Note that this parameter is independent from the deliveryOnly penalty: the penalty affects delivery-only roads (entire road segments), while allowDeliveryOnlyGates controls passage through specific gate points at the entry of delivery zones.
Behavior with other parameters
Avoid: The penalty parameters and options[avoid] cannot be used together for the same road type. If both are specified for the same road type, the request will be rejected with an error. See Avoid for the basic avoidance feature.
routingMode MONETARY: As route calculation is optimized for costs, penalties have no effect. Therefore, only the values 0 (roads are allowed) and 2501 (roads are blocked) are supported. All other values are ignored.
routingMode SHORTEST: The byRoadCategory penalty cannot be used together with options[routingMode]=SHORTEST. The request will be rejected with an error.
routeId: When a routeId is specified, all penalties and allowDeliveryOnlyGates are ignored.
Non-motorized profiles: The penalties deliveryOnly, residentsOnly and toll as well as allowDeliveryOnlyGates are ignored for non-motorized profiles such as BICYCLE or PEDESTRIAN. The penalties byRoadCategory, ferries and railShuttles are applied to all profiles.
Limitations
The penalties parameter will have longer response times. When using this parameter, the air-line distance of all waypoints in a request is limited to 10000 km. Additionally, the air-line distance between any two consecutive waypoints must not exceed 3000 km.
The same limitations apply to allowDeliveryOnlyGates.
Try it in the Penalties code sample.