Routing API v7 Developer's Guide

Truck Routing

The Truck Routing features of the API extends Waypoints, Routing Types, Transport Modes, and Time Aware Routing with truck-specific and time-dependent features.

Truck Routing Mode

Route calculations in Truck Routing Mode take into account any truck-related restrictions. These route calculations also use different Speed Profiles for light, medium, and heavy trucks. The resulting routes are optimized for the least amount of travel time. You can further optimize truck routing for traffic and also support penalizing roads with specific kinds of attributes. See Avoiding Certain Road Types for more information.

When calculating truck routes, we recommend to always use the fastest Routing Mode Type. See Routing Mode Parameter Combinations for more information.

Truck Profile

Truck Profile refers to a set of request parameters that specify the truck attributes used in route calculation, such as:
  1. to identify the relevant speed profile for route computation
  2. to exclude roads and maneuvers with certain restrictions that are violated by a particular truck
The following request parameters are available:
  • truckType
  • trailersCount
  • axleCount
  • shippedHazardousGoods
  • limitedWeight
  • weightPerAxle
  • weightsPerAxleGroup
  • height
  • width
  • length
  • tunnelCategory
  • truckRestrictionPenalty

For more details on how to use these parameters, see Examples for Truck Routing Requests.

Weight Per Axle Group

The truck profile distinguishes weight-per-axle-group from the typical weight-per-axle. The following axle group types are available:
  • single axle group
  • tandem axle group
The weight-per-single-axle and weight-per-tandem-axle correspond directly to the restrictions like on the road signs below.
Figure 1. Road signs related to weight-per-single-axle and weight-per-tandem-axle restrictions
Note: The restrictions on truck weight-per-single-axle or weight-per-tandem-axle are present mostly in the US and Australia.

To specify truck weight-per-single-axle or weight-per-tandem-axle use the parameter weightsPerAxleGroup with a group type single or tandem like in the examples below.
// truck with 12 tonnes per single axle group
&weightsPerAxleGroup=single:12

// truck with 16 tonnes per tandem axle group
&weightsPerAxleGroup=tandem:16

// truck with 12 tonnes per single axle group and 16 tonnes per tandem axle group
&weightsPerAxleGroup=single:12;tandem:16

The weight-per-single-axle (group) must not be confused with the weight-per-axle parameter of the truck profile. The routing engine evaluates the weight-per-axle restrictions like on the figure below only against the latter value.
Figure 2. Road sign related to weight-per-axle restriction

Truck Speed Profile

The Routing API v7 uses different speed profiles for light, medium, and heavy trucks. When computing a route, you can specify one of the following:
  • light truck (default) – uses speeds that are lower than those for regular cars
  • medium truck (18 tons > limitedWeight > 7.5 tons) – uses speeds that are lower than those for light trucks
  • heavy truck (limitedWeight > 18 tons) – uses speeds that are lower than those for medium trucks

Truck Restrictions

Routes calculated in Truck Routing Mode take the following Truck Restrictions into account:
  • Legal restrictions – applies to links and maneuvers prohibited for trucks
  • Physical restrictions – applies to physical attributes of a vehicle, for example: weight, weight per axle, height, width, or length
  • Hazardous materials restrictions – applies to cargos with hazardous materials. See Hazardous Materials.
  • Tunnel categories – applies to a tunnel category for hazardous materials. See Tunnel Categories.
  • Trailer restrictions – relates to vehicle trailers. See Trailer Restrictions.
  • Axle restrictions – relates to a vehicle axle count. See also Conditional Restrictions.
  • Time dependent restrictions – applies to restrictions for a specific period of time. Routes using roads that violate a time dependent restriction are penalized if the vehicle reaches the road while the restriction is valid. However, this restriction is not taken into account if the road is reached outside of the restricted period or if the route is calculated in the planning mode. See Using Time Aware Routing.
  • Conditional restrictions – applies to legal or physical restrictions dependent on time or Truck Profile, where the Truck Profile may include attributes such as truckType, trailersCount, axleCount, shippedHazardousGoods, and tunnelCategory. See Conditional Restrictions.

Hazardous Materials Restrictions

This restriction applies to truck cargo, where the resulting route excludes roads on which hazardous materials are prohibited from being transported. The rules for excluding roads with such restrictions include:
  • when the truck contains hazardous materials, roads prohibited for shipment of dangerous materials are always excluded from route calculation
  • when the request specifies shippedHazardousGoods=harmfulToWater, roads prohibited for shipment of water pollutants are excluded from route calculation
  • when the request specifies shippedHazardousGoods=explosive,flammable, roads prohibited for shipment of explosive and flammable materials are excluded from route calculation
  • when the request specifies a hazardous material that is in the truck, roads prohibited for shipment of that specific hazardous material are excluded from route calculation

Although some hazardous material categories overlap, the routing engine does not implicitly map the hazardous materials to restricted goods. For example, if the cargo specifies combustible materials or gas (which could be flammable), roads prohibited for flammable materials are not excluded from route calculations. Similarly, if the cargo specifies poison or gas (which could be toxic), roads prohibited for materials that are poisonous upon inhalation are not excluded from route calculations.

Tunnel Categories

Tunnel Categories (tunnelCategory) specify which dangerous goods are not allowed to enter the regulated tunnel. The categories range from B to E with B being the least restrictive. The tunnel categories provided in a Truck Profile excludes tunnels that are equally or more restrictive from the route calculation.

Because tunnel categories include restrictions for dangerous goods, you might expect the routing engine to automatically select the most appropriate tunnel category based on the shippedHazardousGoods parameter. However, this is not the case. If you have set the shippedHazardousGoods parameter, you must still set the tunnelCategory parameter as well. The routing engine cannot calculate the value for tunnelCategory based on the shippedHazardousGoods alone.

Trailer Restrictions

The Routing API v7 can distinguish between trailer and semi-trailer restrictions. The rules for excluding roads with trailer restrictions are as follows:
  • if trailersCount > 0 – roads prohibited for trucks with trailers are excluded from route calculation
  • if truckType = tractorTruck and trailersCount > 0 – roads prohibited for tractors with semi-trailers are excluded from route calculation
Note: Semi-trailer restrictions are mostly used in North America.

Conditional Restrictions

Conditional restrictions are the restrictions that apply only to trucks with a particular type of trailer, with a particular number of axles or a cargo with a specific material. If a truck violates a conditional restriction, it is implied that the truck violates all of the conditions specified.

Typically, a conditional restriction is a physical attribute limit dependent on a trailer type where the restriction applies only to trucks of that trailer type. For example, suppose a road prohibits trucks with trailers that weigh over 20 tons (trailersCount >= 1 and limitedWeight > 20 tons). This restriction applies to trucks of any type with at least one trailer and a total weight exceeding 20 tons. However, this restriction does not apply to trucks without trailers even if they exceed 20 tons. Similarly, this restriction also does not apply to trucks with trailers that weigh less than 20 tons.

Note: A conditional restriction does not mean two separate restrictions on one road.