Vehicle Parametrization

This use-case describes the different approaches that can be used to parametrize a vehicle The term vehicle describes what is being routed or planned for. Vehicles are used in route calculation, distance matrix calculation and effectively also in tour planning. In route calculation, vehicle properties like overall size, weight and speed are in focus. In tour planning, it is vehicle properties like capacity and availability. Commonly a vehicle is motorized, like a truck - including its trailer or a car. However also a bike or even a pedestrian are included in this definition.. This includes the use of reference profiles The reference profile is a stored profile shipped with xServer 2 which can be used directly or as a basis of customization., stored profiles A stored profile is a (partial) profile persisted as an XML file. and request profiles The request profile is a partial profile provided in object form for a specific request. Any parameter which is not set in the request profile will be taken from the stored profile. (see Profile mechanism for a detailed description).

Benefits

By selecting the right vehicle profile A profile is a collection of parameters used to configure the request. Full profiles consist of a number of specialized sub-profiles like the VehicleProfile which describes the properties of a vehicle. and/or providing customized parameters for your vehicles you can substantially improve the results of all your routing A route corresponds to a path of a vehicle through the underlying transport network. The main attributes of a route are the distance and the time that the vehicle travels along the path. operations.

This includes:

Improved routing taking into consideration your vehicle's specific properties like weight, physical dimensions and cargo
Better results for estimates like driving time or emissions
Precise toll calculation

Storing commonly used parameters as a profile makes it easy and efficient to reference them in requests.

Prerequisites

Check if the following prerequisites are fulfilled before you start with the use case:

Technical specification and physical properties of the vehicle are available
Use-cases for vehicle profile are known. For example is emission calculation needed?
XML-Editor (optional)

Concepts

Parametrization with a stored profile

The PTV xServer already comes with a number of stored profiles. Each of these stored profiles attempts to match a class of vehicles. A list can be found here in the dashboard under Configuration Files.

To use reference or other stored profiles they have to be specified with the request. To enable this each request type can reference a storedProfile.

A corresponding JSON JSON (JavaScript Object Notation) is an open standard format for which human-readable text is used to transmit information consisting of attribute–value pairs. It is the first-address data format used for asynchronous browser/server communication (AJAX). routing request for the PTV xRoute service calculateRoute endpoint might be:

{
	"storedProfile": "car.xml",
	"waypoints": [
		{ "$type": "OffRoadWaypoint", "location": {"offRoadCoordinate": { "x": 6.1256572, "y": 49.5983745 } } },
		{ "$type": "OffRoadWaypoint", "location": {"offRoadCoordinate": { "x": 6.1256572, "y": 49.4816576 } } }
	]
}

Customization of a stored profile

Sometimes no reference profile matches the specific parameters of a vehicle. For example consider a tanker truck transporting gasoline. Due to the hazardous nature of the cargo it will not be legal to drive on certain streets or pass through certain tunnels. To consider this during routing we can create a customized stored profile. To not have to specify every detail of our truck we can derive our profile from an existing stored profile (see Parent Mechanism and Effective Profiles). Then we can selectively adjust the parameters important for our use-case.

To do so first we create a new stored profile XML file in which we can adjust the vehicle sub-profile:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile version="2" parent="truck40t.xml" >
		<vehicleProfile>
				<!-- Customized parameters for vehicle go here -->
		</vehicleProfile>
</profile>

The parent profile is defined using the parent attribute of the profile tag. The path is always relative to the current profile. In this example we chose the reference profile truck40t.xml.

As our vehicle is a tanker truck which carries gasoline we have to set the appropriate dangerous goods and tunnel restriction code so they can be obeyed during routing. Doing this with the appropriate values for Germany the profile would then look like this:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<profile version="2" parent="truck40t.xml" >
	<vehicleProfile>
		<load hazardousGoodsTypes="HAZARDOUS" tunnelRestrictionCode="D">
	</vehicleProfile>
</profile>

The customized profile can then be stored either on the server in the conf/profiles directory or in an accessible HTTP location. After that it can be used like any other stored profile (see Profile types).

If you are using an XML editor you should configure it to use the StoredProfile.xsd schema. This allows you to perform a basic validation of the profile before deploying it. Depending on the editor it might also give you additional help while editing.

Customization using the request profile

Depending on the specific use-case it might not be possible or desirable to use only stored profiles. This is usually the case in the presence of parameters that vary unpredictable with each request. For such cases the vehicle profile can be customized using the so called request profile. The request profile is an optional part of each request type in the PTV xServer API.

{
	"storedProfile": "truck40t.xml",
	"requestProfile": {
		"vehicleProfile": {}
	},
	"waypoints": [
		{ "$type": "OffRoadWaypoint", "location": {"offRoadCoordinate": { "x": 6.1256572, "y": 49.5983745 } } },
		{ "$type": "OffRoadWaypoint", "location": {"offRoadCoordinate": { "x": 6.1256572, "y": 49.4816576 } } }
	]
}

We could use this to parametrize our tanker trucks without using a custom stored profile.

{
	"storedProfile": "truck40t.xml",
	"requestProfile": {
		"vehicleProfile": {
			"load": {
				"hazardousGoodsTypes": "HAZARDOUS",
				"tunnelRestrictionCode": "D"
			}
		}
	},
	"waypoints": [
		{ "$type": "OffRoadWaypoint", "location": {"offRoadCoordinate": { "x": 6.1256572, "y": 49.5983745 } } },
		{ "$type": "OffRoadWaypoint", "location": {"offRoadCoordinate": { "x": 6.1256572, "y": 49.4816576 } } }
	]
}

In contrast to stored profiles, request profiles cannot be cached efficiently by the server. Depending on how many parameters you overwrite in the request profile this might create a noticeable performance impact for small requests.