Visualizing vehicle restrictions

📘

Note

The 3.1 version of this API has been deprecated. For continued support and feature development, upgrade to the latest 3.2 version.

📘

Note

This functionality is available for the HARP engine only.

The vehicle profile API presented in this document is currently in beta and its behaviour may change in future releases.

Overview

Commercial vehicles especially heavy-duty trucks must comply with various road restrictions related to dimensions, weight, hazardous materials, and tunnel access. These restrictions vary across locations and are often displayed as icons or signs on maps. HERE Maps API for JavaScript provides a way to visualize all vehicle restrictions on the map by means of the "vehicle restrictions" feature in the appropriate mode. Features and modes allow you to control which types of map data are rendered. For example, activating the "vehicle restrictions" feature in the "active & inactive" mode will display all available restriction icons and signs. For more details on how to use features and modes, see Customize map display through features and modes.

To help developers visualize only relevant restrictions for a specific vehicle and/or date of travel, HERE Maps API for JavaScript provides 2 APIs:

• Vehicle Profile API: that uses a configurable vehicle profile. The API ensures that only those restrictions which apply to the defined truck are shown on the map.
• Time Based Vehicle Restrictions API: that allows to filter non permanent truck restrictions based on the date and time of travel.

These features are particularly useful to transport planners and logistics companies, as it allows them to focus on the constraints that matter for their specific vehicles, improving route planning.

This guide explains how to configure and use H.service.omv.Provider#setVehicleSpecs with the H.service.omv.Provider.ITruckSpecs interface to filter truck restrictions on the map.
Moreover, it provides examples of how to use H.service.omv.Provider#setTimeRestriction to filter truck restrictions based on the date and time of travel.

Please refer to the API reference page H.service.omv.Provider for more.

📘

Note

Please be aware that some restrictions may not be visible on the map at all times due to their large number and visualization constraints, such as icon overlap and collision detection.

Getting Started:

1. Setup the map to use vector.normal.logistics

Heavy goods vehicles (HGVs) premium properties are available in the additional advanced_roads data layer - see Advanced Roads for more details.

HERE Maps API for JavaScript provides the vector.normal.logistics layer requesting advanced_roads data out of the box. The logistics map style has been designed to bring the following map elements into focus: industrial areas, road exit numbers and names, built-up areas, truck/regular toll roads and logistics-related POIs such as truck POIs, cargo and delivery POIs, logistic area types POIs.

const platform = new H.service.Platform({
  apikey: "YOUR API KEY",
});

const engineType = H.Map.EngineType.HARP;

const defaultLayers = platform.createDefaultLayers({ engineType });

// Instantiate and display a map
const map = new H.Map(
  document.getElementById("map"),
  defaultLayers.vector.normal.logistics,
  {
    zoom: 7,
    center: { lat: 51.509865, lng: -0.118092 },
    engineType
  }
);

// ... rest of the application

See H.service.Platform#createDefaultLayers API reference page to learn about the available default layers.

2. Enable vehicle restriction feature

The rendering of vehicle restrictions can be enabled via features and modes.

Please refer to Customize map display through features and modes to learn more about features and modes and how to properly use them.

const style = map.getBaseLayer().getProvider().getStyle();
const enabledFeatures = style.getEnabledFeatures();
enabledFeatures.push({ feature: 'vehicle restrictions', mode: 'active & inactive'});
style.setEnabledFeatures(enabledFeatures);

Vehicle Profile API

Setting a vehicle profile

To apply the filtering logic, define your vehicle profile using H.service.omv.Provider#setVehicleSpecs:

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  // ... other relevant attributes
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

The object must conform to the H.service.omv.Provider.ITruckSpecs interface.

Table of H.service.omv.Provider.ITruckSpecs attributes

• grossWeightInKilograms
• heightInCentimeters
• lengthInCentimeters
• widthInCentimeters
• trailerCount
• truckType
• hazardousMaterial
• tunnelCategory
• kpraInCentimeters
• axleCount
• weightPerAxleInKilograms
• weightPerAxleGroup
• preferredTruckRouteTypes

grossWeightInKilograms

Description: Gross vehicle weight in kilograms, including trailers and shipped goods when loaded at capacity.

Behaviour: The value set for grossWeightInKilograms is checked against the hgv_restriction:weight value in the vector tile data.

Restriction is shown if the truck's gross weight is greater than the restricted value.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a gross weight restriction
map.getViewModel().setLookAtData({
  zoom: 18,
  position: { lat: 51.51032, lng: -0.00125 }
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  grossWeightInKilograms: 32000
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only gross weight restrictions relevant to the configured vehicle profile are displayed.

heightInCentimeters

Description: Total vehicle height in centimeters.

Behaviour: The value set for heightInCentimeters is checked against the hgv_restriction:height value in the vector tile data.

Restriction is shown if truck height is greater than the restricted value.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a height restriction
map.getViewModel().setLookAtData({
  zoom: 19.8,
  position: { lat: 51.51235, lng: -0.00872 }
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  heightInCentimeters: 410
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only height restrictions relevant to the configured vehicle profile are displayed.

lengthInCentimeters

Description: Total vehicle length in centimeters.

Behaviour: The value set for lengthInCentimeters is checked against the hgv_restriction:length value in the vector tile data.

Restriction is shown if length is greater than the restricted value.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a length restriction
map.getViewModel().setLookAtData({
  zoom: 17,
  position: {lat: 45.5297, lng: -122.6659}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  lengthInCentimeters: 1800
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only length restrictions relevant to the configured vehicle profile are displayed.

widthInCentimeters

Description: Total vehicle width in centimeters.

Behaviour: The value set for widthInCentimeters is checked against the hgv_restriction:width value in the vector tile data.

Restriction is shown if width is greater than the restricted value.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a width restriction
map.getViewModel().setLookAtData({
  zoom: 18.35,
  position: {lat: 55.87311, lng: -4.3290}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  widthInCentimeters: 280
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only width restrictions relevant to the configured vehicle profile are displayed.

trailerCount

Description: Number of trailers attached to the vehicle.

Behaviour: The value set for trailerCount is checked against the hgv_restriction:trailers value in the vector tile data only if the corresponding hgv_restriction_shield_text value is either One or more, Two or more, or Three or more.

Restriction is shown if the trailer count is greater than or equal to the restricted value.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a trailer restriction
map.getViewModel().setLookAtData({
  zoom: 16.6,
  position: {lat: 40.8602, lng: -73.9626}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  trailerCount: 1
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only trailer count restrictions relevant to the configured vehicle profile are displayed.

truckType

Description: Defines the type of truck - it can be either:

• H.service.omv.Provider.ITruckSpecs.TruckType.STRAIGHT: A truck on a single frame with a permanently attached cargo area.
• H.service.omv.Provider.ITruckSpecs.TruckType.TRACTOR: A towing vehicle that can pull one or more semi-trailers (AKA semi-truck.)

Behaviour: The value set for truckType is checked against the hgv_restriction:trailers value in the vector tile data only if the corresponding hgv_restriction_shield_text value is Semi or tractor with trailers.

Restriction is shown if the truck type matches the restriction.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a truck type restriction
map.getViewModel().setLookAtData({
  zoom: 17.7,
  position: {lat: 41.3706, lng: -81.8233}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  truckType: H.service.omv.Provider.ITruckSpecs.TruckType.TRACTOR
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only truck type tractor restrictions relevant to the configured vehicle profile are displayed.

// Center the map at a location with a truck type restriction
map.getViewModel().setLookAtData({
  zoom: 17.7,
  position: {lat: 41.3706, lng: -81.8233}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  truckType: H.service.omv.Provider.ITruckSpecs.TruckType.STRAIGHT
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only truck type straight restrictions relevant to the configured vehicle profile are displayed.

hazardousMaterial

Description: Specifies a bitmask of hazardous materials carried by the vehicle - please refer to H.service.omv.Provider.ITruckSpecs.HazardousMaterial for the available values.

Behaviour: The value set for hazardousMaterial is checked against the hgv_restriction:hazmat value in the vector tile data only if the corresponding hgv_restriction_shield_text value does not contain a tunnel category.

Restriction is shown if it matches any declared hazardous material. Special labels also apply to unknown or unspecified hazardous types.

If this value is not defined, the restriction will not be displayed.

📘

Note

Setting this property will not automatically setup the corresponding tunnel category. It is recommended to set the tunnelCategory property as well, to ensure that the vehicle profile is checked against tunnel restrictions.

Hazardous Material Mapping:

Example:

// Center the map at a location with a hazardous material restriction (flammable and explosive)
map.getViewModel().setLookAtData({
  zoom: 19.3,
  position: { lat: 37.7856, lng: -122.3915 }
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  hazardousMaterial:
    H.service.omv.Provider.ITruckSpecs.HazardousMaterial.FLAMMABLE |
    H.service.omv.Provider.ITruckSpecs.HazardousMaterial.EXPLOSIVE
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only hazmat restrictions relevant to the configured vehicle profile are displayed.

tunnelCategory

Description: Specifies the cargo tunnel restriction code.

For more information on tunnel categories, please refer to the ADR 2025 - Agreement concerning the International Carriage of Dangerous Goods by Road.

Behaviour: The value set for tunnelCategory is checked against the hgv_restriction:hazmat value in the vector tile data only if the corresponding hgv_restriction_shield_text value does contain a tunnel category.

A restriction is shown if it is equal to or more restrictive than the vehicle's tunnel category.

The categories range from B to E:

• Vehicle's tunnel category set to B - transport is forbidden through tunnels displaying signs: B,C,D or E
• Vehicle's tunnel category set to C - transport is forbidden through tunnels displaying signs: C,D,E
• Vehicle's tunnel category set to D - transport is forbidden through tunnels displaying signs: D,E
• Vehicle's tunnel category set to E - transport is forbidden through tunnels displaying sign E only

If this value is not defined, the restriction will not be displayed.

📘

Note

Setting this property will not automatically setup the corresponding hazardous materials bitmask. It is recommended to set the hazardousMaterial property as well, to ensure that the vehicle profile is checked against hazardous materials restrictions.

Tunnel Category Mapping:

Example:

// Center the map at a location with a tunnel category B restriction
map.getViewModel().setLookAtData({
  zoom: 17.35,
  position: {lat: 59.34390, lng: 18.0203}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  tunnelCategory: H.service.omv.Provider.ITruckSpecs.TunnelCategory.B
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only tunnel category restrictions relevant to the configured vehicle profile are displayed.

// Center the map at a location with a tunnel category B restriction
map.getViewModel().setLookAtData({
  zoom: 17.35,
  position: {lat: 59.34390, lng: 18.0203}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  tunnelCategory: H.service.omv.Provider.ITruckSpecs.TunnelCategory.E
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only tunnel category restrictions relevant to the configured vehicle profile are displayed.

kpraInCentimeters

Description: Length from the kingpin to the rear axle, in centimeters.

Behaviour: The value set for kpraInCentimeters is checked against the hgv_restriction:kpra value in the vector tile data.

Restriction is shown if the vehicle's value is greater than the restriction.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with a kingpin-to-rear-axle restriction
map.getViewModel().setLookAtData({
  zoom: 15,
  position: {lat: 37.5993, lng: -121.9485}
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  kpraInCentimeters: 1250
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only kingpin-to-rear-axle restrictions relevant to the configured vehicle profile are displayed.

axleCount

Description: Total number of axles in the vehicle.

Behaviour: The value set for axleCount is checked against the hgv_restriction:axles value in the vector tile data. Restriction is shown if the axle count is greater than or equal to the restriction.

If grossWeightInKilograms is also set, both values are checked against the hgv_restriction:wpan_* property and the corresponding hgv_restriction_shield_text value in the vector tile data. The former is used to determine the axle count, while the latter is used to determine the weight limit. Restriction is shown if the set number of axles matches and the weight is greater than the restriction.

If this value is not defined, the restriction will not be displayed.

Example:

// Center the map at a location with an axle count restriction
map.getViewModel().setLookAtData({
  position: { lat: 45.46224, lng: -122.63013 },
  zoom: 18
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  axleCount: 3
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only axleCount restrictions relevant to the configured vehicle profile are displayed.

Some restrictions may show the weight limit for HGVs along with the number of axles in the vehicle, for example:

// Center the map at a location with a weight and axle count restriction
map.getViewModel().setLookAtData({
  position: { lat: 45.4628, lng: -122.6300 },
  zoom: 21
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  grossWeightInKilograms: 22000,
  axleCount: 3
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only restrictions relevant to the configured vehicle profile are displayed.

weightPerAxleInKilograms

Description: Heaviest axle weight in kilograms regardless of axle type or group.

Behaviour: The value set for weightPerAxleInKilograms is checked against the hgv_restriction:wpa value in the vector tile data.

Restriction is shown if the truck’s per-axle weight is greater than then restriction.

If this value is not defined, the restriction will not be displayed.

📘

Note

The per-axle weight is not the same as the axle group weight, which is defined by weightPerAxleGroup, yet in case weightPerAxleGroup is not defined, weightPerAxleInKilograms will be compared against the axle group restrictions (hgv_restriction:wpag_*).

Example:

// Center the map at a location with a per-axle weight restriction
map.getViewModel().setLookAtData({
  position: { lat: 64.0834, lng: -21.8334 },
  zoom: 16
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  weightPerAxleInKilograms: 6000
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only per-axle weight restrictions relevant to the configured vehicle profile are displayed.

weightPerAxleGroup

Description: Defines the weight in kilograms of the different axle groups of a truck.

Behaviour: The values set for weightPerAxleGroup are checked against the matching hgv_restriction:wpag_* value in the vector tile data. Each group's weight is compared independently.

Restriction is shown if the group weight is greater than the restriction.

Moreover, the values set are also checked against the prohibited axle group restrictions, such as: hgv_restriction:axles_group_single_axle, hgv_restriction:axles_group_tandem_axle, hgv_restriction:axles_group_triple_axle, hgv_restriction:axles_group_quad_axle and hgv_restriction:axles_group_quint_axle.

When it comes to prohibited axle group restrictions, the weight does not play a role, yet in order to display the restriction, the axle group must be set with a weight greater than zero.

If this value is not defined, the restriction will not be displayed.

📘

Note

The axle group weight is not the same as the per-axle weight, which is defined by weightPerAxleInKilograms, yet in case weightPerAxleInKilograms is not defined, the heaviest defined axle group weight will be compared against the per-axle weight restrictions (hgv_restriction:wpa).

Example:

// Center the map at a location with axle group restrictions
map.getViewModel().setLookAtData({
  position: { lat: -37.0440, lng: 148.8152 },
  zoom: 18.9
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  weightPerAxleGroup: {
    tripleAxleGroupInKilograms: 21000,
  }
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only axle group restrictions relevant to the configured vehicle profile are displayed.

The following shows an example of a prohibited axle group restriction for a tandem axle group (hgv_restriction:axles_group_tandem_axle):

// Center the map at a location with a prohibited axle group restriction
map.getViewModel().setLookAtData({
  position: { lat: 30.4447, lng: -84.28 },
  zoom: 15
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  weightPerAxleGroup: {
    tandemAxleGroupInKilograms: 1,
  }
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs);

Before	After
All vehicle restrictions are displayed.	Only prohibited axle group restrictions relevant to the configured vehicle profile are displayed.

preferredTruckRouteTypes

Description: Specifies the types of truck preferred routes to be displayed for the configured vehicle profile.

Behaviour: The values set for preferredTruckRouteTypes are checked against the matching all_tpr values in the vector tile data.

The list of values supported by the API can be found in this PreferredRouteType docs page.

If this value is not defined, all truck preferred roads are displayed.

📘

Note

To visualize truck preferred roads, the additional truck preferred roads feature must be enabled. Please refer to Enable vehicle restriction feature.

// Center the map at a location with truck preferred roads
map.getViewModel().setLookAtData({
  position: {lat: 49.4944, lng: 8.5268},
  zoom: 13.42
});

const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  preferredTruckRouteTypes: [16]
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs)

Before	After
All truck preferred roads are displayed.	Only the preferred roads relevant to the configured vehicle profile are displayed.

Combining multiple Vehicle Profile attributes

Let's see now one example of a vehicle profile that combines multiple attributes:

// Center the map at a location with multiple vehicle restrictions
map.getViewModel().setLookAtData({
  position: {lat: 59.3310, lng: 18.0191},
  zoom: 15.82
});
const truckSpecs = {
  vehicleType: H.service.omv.Provider.IVehicleSpecs.VehicleType.TRUCK,
  grossWeightInKilograms: 8000,
  lengthInCentimeters: 600,
  heightInCentimeters: 400
};

map.getBaseLayer().getProvider().setVehicleSpecs(truckSpecs)

Before	After
All vehicle restrictions are displayed.	Only restrictions relevant to the configured vehicle profile are displayed.

Time Based Vehicle Restrictions API

The time based vehicle restrictions API allows you to filter out the vehicle restrictions that are not valid for a specific time.

For this use case there are 2 modes in the vehicle restrictions feature that can be used:

• active & inactive differentiated: both active and inactive restrictions are shown, with the inactive ones faded out for differentiation.
• active only: only active restrictions are shown.

Please refer to Enable vehicle restriction feature for more information on how to enable the vehicle restrictions feature with the preferred mode.

The following examples show the usage of the time based vehicle restrictions API in London, both with the active & inactive differentiated and active only modes.

📘

Note

All vehicle access restriction times in the data are expressed in the local time zone where the restriction applies. Each timestamp provided to the API must follow the simplified ISO8601 format: YYYY-MM-DDThh:mm. Specified timestamps are always interpreted as local time; do not include timezone information.

In case a range of time is specified, both the start and end times must be provided in the same format. A restriction is considered active even if it is only partially within the specified time range.

Example:

// Center the map in London
map.getViewModel().setLookAtData({
  zoom: 13,
  position: { lat: 51.5, lng: 0 }
});

// Set the time to August 13, 2025 at 10:00 AM in London
map.getBaseLayer().getProvider().setTimeRestriction("2025-08-13T10:00");
// Alternatively, a range can be specified
// map.getBaseLayer().getProvider().setTimeRestriction(["2025-08-13T10:00", "2025-08-13T12:00"]);

active & inactive differentiated mode

Before	After
All the restrictions are displayed in full colors.	All the active vehicle restrictions are displayed in full colors, while the inactive ones are displayed in faded colors.

active only mode

Before	After
All the restrictions are displayed.	All the active vehicle restrictions are displayed, while the inactive ones are hidden.

Related Resources

• HERE Routing API – Truck Profile
• Vector Tile API – Advanced Layers