Violation mapping in HERE Matrix Routing API v8

Violation mapping allows you to get more granular and relevant information about the violations found in your matrix calculations.

This is achieved by mapping select violation types to user-specified categories 1 or 2.

Mapped violations are grouped in the defined categories instead of being reported with the error code 3, under which all violations are reported by default.

Example use cases:

• A courier company wants to know if a delivery location is accessible by car or if the access is blocked by vehicle restrictions or due to a general traffic closure. Access to this information allows the courier to decide if they should drive to the delivery address or deliver the package on foot.

• A dispatcher of a truck fleet wants to assign petrol-powered trucks to serve areas where diesel engines are banned. In such case, the banned area is specified as an avoid area in the request and the violations of this avoid rule are mapped to a separate category. This allows detection of routes that go through areas with the diesel ban and assign them to petrol-powered trucks.

Error codes for violations

If any of the calculated routes results in a violation, the response contains an array of errorCodes that contains one error code for each origin and destination pair.

Error codes are determined as follows:

Structure

You specify the violation mapping using the violationMapping request parameter. A mapping consists of an array of mapping items.

Each mapping item specifies two aspects: which restrictions are mapped, and to which category they are mapped.

There are three different types of violation mapping items, each with its own configurable properties:

• restriction: Supported for the truck transport mode only.
• traffic : Supported for the truck and car transport modes.
• avoidAreasAndSegments: Supported for the truck and car transport modes.

📘

Note

Currently, violation mapping is supported only for the truck and car transport modes.

Restrictions

Use type: restriction to map violations of restrictions.

Supported restrictions are:

• grossWeight
• currentWeight
• height

Note that only restrictions of the three supported types are considered when mapping violations.

📘

Note

If your use case requires support for additional restriction types, file a support request.

Simple restriction mapping

To create a simple restriction mapping, select a single restriction type and set its value to include.

This example maps violations of grossWeight restrictions to category 1:

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include"
	}
]

As a result of the example mapping, a violated restriction must include a grossWeight condition in order for it to be mapped to the user-specified category.

Other violations are unmapped.

Mapping multiple restriction types

To map multiple restriction types to a user-specified category in a single mapping item, set the values to ignore.

Assigning the value ignore to a property means that a violated restriction may include the associated condition, but is not required to.

As a result, when either one of the specified restrictions is violated, the violation is mapped to the user-specified category.

This example maps either grossWeight restrictions or currentWeight restrictions to category 1:

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "ignore",
		"currentWeight": "ignore"
	}
]

You can achieve the same results by creating two separate mapping items, one for each restriction type.

Both items must use the include value.

See the following example:

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include"
	},
	{
		"category": 1,
		"type": "restriction",
		"currentWeight": "include"
	}
]

The example with a single mapping item using the ignore value and the example with two mapping items using the include value are functionally equivalent.

📘

Note

If you created mapping with two restriction types and set the value to include for both, the mapping would take effect only if both of the restrictions are violated at the same time. If only one of them is violated, the mapping doesn't take effect. Applying this to the initial example, there are no restrictions that have both a grossWeight condition and a currentWeight condition simultaneously. Setting the value to include for both conditions means that these violations are never mapped to the user-defined category.

Additional restriction conditions

Restriction mapping items can use the following additional conditions:

• timeDependent : The restriction has a time dependency.
• bridge : The restriction is on a bridge.

These conditions are not restriction types themselves, but can be used to further filter violations.

By default additional conditions are assigned the value ignore so they are not considered when deciding which violations to map.

Use the value include to require a condition, and the value exclude to forbid a condition.

This example maps either grossWeight violations or currentWeight violations to category 1, but only if they occur on a bridge.

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "ignore",
		"currentWeight": "ignore",
		"bridge": "include"
	}
]

📘

Note

Most restrictions that occur on a bridge also extend beyond the length of the bridge. This means that, while it is possible to detect when violations occur on bridges, clients should also expect those same routes to contain violations that are not on a bridge.

This example maps grossWeight violations to category 1, but only if they are not time-dependent.

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include",
		"timeDependent": "exclude"
	}
]

Traffic

Use type: traffic to map violations of road closures.

In this example, such violations are mapped to category 1.

[
	{
		"category": 1,
		"type": "traffic"
	}
]

Additional restriction conditions

Traffic mapping items can use the following additional condition:

• bridge : The restriction is on a bridge.

In this example, all traffic violations are mapped to category 1 unless they happen on a bridge.

When a traffic violation is detected on a bridge, it's unmapped and causes a code 3 error.

{
	"category": 1,
	"type": "traffic",
	"bridge": "exclude"
}

Avoiding areas and segments

Use type: avoidAreasAndSegments to map violations of avoid[areas] or avoid[segments].

In this example, such violations are mapped to category 2.

[
	{
		"category": 2,
		"type": "avoidAreasAndSegments"
	}
]

Mapping to separate categories

Each item in the violationMapping array can map violations to either of the user-specified categories.

If a violation matches multiple items in the array, it is mapped to the specified category for each matched item.

In this example:

• grossWeight violations that occur on a bridge are mapped to category 1.
• grossWeight violations that do not occur on a bridge are mapped to category 2.
• All traffic violations are also mapped to category 2.

[
	{
		"category": 1,
		"type": "restriction",
		"grossWeight": "include",
		"bridge": "include"
	},
	{
		"category": 2,
		"type": "restriction",
		"grossWeight": "include",
		"bridge": "exclude"
	},
	{
		"category": 2,
		"type": "traffic"
	}
]