This document explains the CartoTypeRouteProfile XML format, used in .ctprofile files. These files are used to store route profiles, which are used to customize the behavior of the route calculation system. For example, it's possible to make some types of roads more or less preferable than others, or to forbid them entirely, and to set the type of vehicle, for instance to a car, heavy goods vehicle or bicycle.
<CartoTypeRouteProfile>
The <CartoTypeRouteProfile> element contains the whole content of the file. It has the following attributes. The default values, which are used when reading a profile from an XML file, are those of the 'car' profile.
turn_time = integer
The estimated time in seconds taken for any turn at a junction that is not a slight turn or simply going straight ahead. Default = 4;
u_turn_time = integer
The estimated time in seconds taken for a U-turn, defined as a turn very close to 180 degrees (within 1/32 of a circle = 11.75 degrees). Default = 300.
cross_traffic_turn_time = integer
The estimated time in seconds taken for a turn across the traffic: that is, a left turn in drive-on-right countries, or a right turn in drive-on-left countries. The time is used when turning from the right of way to a lower-rank road. Default = 8.
traffic_light_time = integer
The estimated delay in seconds caused by traffic lights. Default = 10.
shortest = true or false
If true, ignore the speed, bonuses, and turn times; get the shortest route, not the fastest. Default = false.
obey_one_way = true or false.
If true, obey one-way restrictions. Default = true.
toll_penalty = number
The penalty applied to toll roads as a number between zero and one. The value 1 means that no toll roads will be used, 0.5 makes toll roads half as desirable as non-toll roads
of the same road type, and so on. The value 0 means that no penalty is applied to toll roads. Values outside the range 0...1 are clamped to that range. Default = 0.
Elements contained by <CartoTypeRouteProfile>
The <CartoTypeRouteProfile> element contains
one or more <vehicle> elements, unless this profile is intended for pedestrians
zero or more <road> elements
zero or more <gradients_apply_to> elements
zero or more <gradient> elements
<vehicle>
The <vehicle> element defines the type of vehicle for which this profile is used. It is used only for non-pedestrian profiles. One or more <vehicle> elements may be used if restrictions for one or more types must be obeyed. For example, it is possible to have both "light_goods" and "hazardous" <vehicle> elements. It has the following attribute:
type = string
The vehicle type. One of "bicycle", "motorcycle", "car", "high_occupancy", "light_goods", "heavy_goods", "bus", "taxi", "tourist_bus", "emergency", "hazardous".
<road>
A <road> element contains the weight and other attributes of a certain road type. There can be up to 32 <road> elements: one for each road type. Attributes for missing road types are given the default values for the 'car' profile, but for clarity all road types should be specified. The <road> element has the following attributes:
type = string
The road type. There are 32 possible road types: "motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link", "tertiary", "unclassified", "residential", "track", "service_road", "pedestrian_road", "vehicular_ferry", "passenger_ferry", "living_street", "cycleway", "path", "footway", "bridleway", "steps", "unknown_road_type", "unpaved_road", "other_road_type_0", "other_road_type_1", "other_road_type_2", "other_road_type_3", "other_road_type_4", "other_road_type_5", "other_road_type_6", "other_road_type_7". The road types mainly follow OpenStreetMap usage.
speed = number
The expected speed of travel in kilometres per hour.
bonus = number
A bonus (if positive) or penalty (if negative) in notional km per hour to be added to a road's weighting to make it more or less likely to be used. For example, a penalty of 1kph is applied to walking routes along major roads because it is pleasanter to walk along quieter minor roads.
obey_one_way = true or false
If this is set it overrides, for this road type, the global setting of obey_one_way in the <CartoTypeRouteProfile> element.
Elements contained by <road>
The <road> element may contain one or more <override> elements.
<override>
The <override> element allows you to override restrictions for various types of vehicle. For example, if <override type='car'/> appears in the <road> element for "pedestrian_road", cars will be allowed access to normally forbidden pedestrian roads. There is one attribute:
type = string
The vehicle type. One of "all", "all_motor", "bicycle", "motorcycle", "car", "high_occupancy", "light_goods", "heavy_goods", "bus", "taxi", "tourist_bus", "emergency", "hazardous".
<gradients_apply_to>
The <gradients_apply_to> element specifies a type of road for which gradient weightings apply. For example, gradient weightings don't normally apply to steps. There is one attribute:
type = string
The road type. One of "motorway", "motorway_link", "trunk", "trunk_link", "primary", "primary_link", "secondary", "secondary_link", "tertiary", "unclassified", "residential", "track", "service_road", "pedestrian_road", "vehicular_ferry", "passenger_ferry", "living_street", "cycleway", "path", "footway", "bridleway", "steps", "unknown_road_type", "unpaved_road", "other_road_type_0", "other_road_type_1", "other_road_type_2", "other_road_type_3", "other_road_type_4", "other_road_type_5", "other_road_type_6", "other_road_type_7".
<gradient>
The <gradient> element gives the speeds and bonuses for gradients. Gradients are used only if the map contains height data in a layer called "terrain-height-metres" generated from USGS height data. The attributes are:
type = string
The gradient type. One of "up0", "up1", "up2", "up3", "down0", "down1", "down2", "down3". The four gradients are 0: flat: up to 1 in 100 (1%); 1: gentle: up to 1 in 25 (4%); 2: steep: up to 1 in 12.5 (8%), and 3: very steep: over 1 in 12.5 (8%).
speed = number
A speed added to the normal speed for roads with this gradient. These values are intended for cycling, walking, hiking and running profiles, where speeds are generally the same for different types of road, but can change according to the gradient.
bonus = number
A bonus added to the normal bonus for roads with this gradient.
