| service method | RoadEditor | legacy dynamic routing | feature layer | high-performance routing |
|---|---|---|---|---|
| calculateRouteInfo | x | x | x | x |
| calculateRoute | x | x | x | x |
| calculateExtendedRoute | x | x | x | x |
| calculateTour | x1 | - | x1 | - |
| calculateAdvancedTour | x1 | - | x1 | x |
| calculateMatrixInfo | x | x | x | x |
| calculateReachableObjects | - | - | x2 | - |
| searchForReachableObjects | - | - | x2 | - |
| calculateIsochrones | - | x | x2 | - |
1 calculateTour and calculateAdvancedTour do not support RoadEditor by database and feature layers with enabled time-dependency.
2 These methods supports only speed and blocking information from feature layers, non-blocking malus values (such as with preferred routes) will be ignored.
In general the optimization is part of a vehicle profile. If this option is set in the request it dominates the value defined in the profile.
Set the RoutingParameter OPTIMIZATION. The value has a range from 0 to 100. The maxima lie in between: 30 - shortest, 80 - fastest. Most profiles use 80 as standard. The profile pedestrian uses the value 0.
parameter="OPTIMIZATION" value="50"
Send the request.
In general the speed profile is part of a vehicle profile. If this option is set in the request it dominates the value defined in the profile.
Set the RoutingParameter SPEED_PROFILE. The speed profile has to be described as a string of 16 comma separated values representing the 2 speeds [km/h] per network class. The values in the example comply with a fast truck.
parameter="SPEED_PROFILE" value="80,55,65,30,55,23,45,20,40,18,30,15,12,17,6,4"
Send the request.
Calculate can take into account that certain kinds of roads can be avoided. If this option is set in the request it dominates the value defined in the profile.
Several parameters are in charge of the avoidance:
AVOID_TOLLROADS
|
avoid roads where a toll is charged |
AVOID_VIGNETTEROADS
|
avoid roads where a vignette is necessary |
AVOID_HIGHWAYS
|
avoid highways |
AVOID_FERRIES
|
avoid ferries |
AVOID_RESIDENTS_ONLY
|
avoid roads |
AVOID_URBAN_AREAS
|
avoid urban areas |
AVOID_RAMPS
|
avoid ramps |
AVOID_NATIONALNAMEDTOLL_ROADS
|
avoid roads where a national "named" toll is charged (e.g. EcoTax in France). See API documentation for format of this value. |
Set the RoutingParameter AVOID_*. The value has a range from -99 (favour over other roads) to 2501 (these roads are blocked). Values in between are taken into calculation of the cost factor of the road segment. The value 0 is neutral. For example block highways for bicycles:
parameter="AVOID_HIGHWAYS" value="2501"
Send the request.
Define a list of countries to ban in route calculation.
Set the RoutingParameter EXCLUDE_COUNTRIES.
The value has to be described as a string of comma separated values. Permitted values are integration unit codes.
parameter="EXCLUDE_COUNTRIES" value="49,52" //Germany, Luxemburg
Send the request.
Define a list of countries to use exclusively in route calculation.
Set the RoutingParameter ROUTING_COUNTRIES.
The value has to be described as a string of comma separated values. Legal values are integration unit codes.
parameter="ROUTING_COUNTRIES" value="41,43,75" //Switzerland, Austria, Liechtenstein
Send the request.
Change the language which is used for the directions in the route maneuvers and for the currency description in the toll information.
The language of the currency description depends on the map data. That means not all languages supported by the PTV xRoute server in general may be supported by the current map data. If the map does not support the requested language, the currency description will be returned in English.
The language of localities, streets, and other proper names always corresponds to the language used on road signs in the particular country and can not be influenced by the user. In some countries, several languages may be used in parallel. In this case, the language depends on the configured map data.
Set the RoutingParameter ROUTE_LANGUAGE.
Legal values are all language codes (ISO 639-1 Codes) specified in the configuration file RLTrans_ISO639-1.xml. For example:
| DE | German |
| EN | English |
| FR | French |
| NL | Dutch |
| ES | Spanish |
| PT | Portuguese |
| IT | Italian |
| SV | Swedish |
| DA | Danish |
This file contains translations for standardized direction text fragments in 20 different languages. To extend the file with a custom language, yet another XML element Language that contains translations for all text fragments in XML format has to be provided. Furthermore, the attribute LanguageCount in the top element TurnTexts has to be adjusted.
parameter="ROUTE_LANGUAGE" value="NL" //Dutch
Send the request.
Set a start time and change the flag to destination time.
Set the RoutingParameter START_TIME.
The parameter is used as start time or destination time depending on the flag IS_DESTTIME. The time has to be described as a string using the TimeInstant syntax: CCYY-MM-DDThh:mm:ss-hh:mm. The difference to UTC is subtracted. If you want to use the actual time set "NOW" do not set the parameter.
parameter="START_TIME" value="2008-06-30T10:00:00-01:00" // 30 th June 2008, 10 o'clock in Central Europe
Set the RoutingParameter IS_DESTTIME.
Defines how the START_TIME value has to be interpreted:
| true | START_TIME has to be interpreted as destination time |
| false | START_TIME has to be interpreted as start time |
parameter="IS_DESTTIME" value="true"
Send the request.
CalculateExtendedRoute can deliver toll cost information. Therefore the type and the dimensions of the vehicle must be set.
Set the VehicleOption TYPE in the CountryInfoVehicleOptions.
The legal values are: CAR, VAN (truck less than 7.5 t total weight), TRU (truck more than 7.5 t total weight), TRL (truck with trailer), COM (combustible load), HAZ (water hazardous load), MOT (motorbike), BIK (bicycle), CAM (camper/minivan), BUS, PED (pedestrian).
parameter="TYPE" value="TRL" //truck with trailer
Set the VehicleOption TOTAL_WEIGHT in the CountryInfoVehicleOptions.
This is the maximum weight of the vehicle in [kg]. It is used e.g. on German (trucks >12t) or Austrian (trucks >3,5t) motorways.
parameter="TOTAL_WEIGHT" value="40000" //[kg]
Set the VehicleOption TRAILER_WEIGHT in the CountryInfoVehicleOptions.
This is the maximum weight of the trailer in [kg]. It is used e.g. on the Giurgiu-Ruse bridge at the Romanian/Bulgarian border (Trailers with a maximum weight <= 750kg -> 8 USD, Trailers with a maximum weight > 750kg -> 15 USD).
parameter="TRAILER_WEIGHT" value="20000" //[kg]
Set the VehicleOption AXLE_WEIGHT in the CountryInfoVehicleOptions.
This is the maximum axle weight in [kg]. No example known.
parameter="AXLE_WEIGHT" value="13000" //[kg]
Set the VehicleOption NUMBER_OF_AXLES in the CountryInfoVehicleOptions.
It is used e.g. on Croatian motorways (truck with 3 axles -> category=III, truck with 4 axles -> category=IV).
parameter="NUMBER_OF_AXLES" value="4"
Set the VehicleOption EMISSION_CLASS in the CountryInfoVehicleOptions.
It is used e.g. on German motorways (emission class euro 5 -> toll collect class A).
parameter="EMISSION_CLASS" value="EURO_4"
Set the VehicleOption HEIGHT in the CountryInfoVehicleOptions.
It is used e.g. on French motorways where trucks higher then 3m have another cost category.
parameter="HEIGHT" value="400" //[cm]
Set the VehicleOption LENGTH in the CountryInfoVehicleOptions.
It is used e.g. on Macedonian motorways (truck <=10.5m -> category=3, truck >10.5m -> category=4).
parameter="LENGTH" value="2000" //[cm]
Set the VehicleOption WIDTH in the CountryInfoVehicleOptions.It is used e.g. on the ferry from Romanshorn to Friedrichshafen (Lake Constance) where vehicles wider than 2m are more expensive.parameter="WIDTH"
value="250" //[cm]
Set the VehicleOption NUMBER_OF_PASSENGERS in the CountryInfoVehicleOptions.
It is used e.g. in the Munt la Schera tunnel (Switzerland). One passenger costs 2 EUR.
parameter="NUMBER_OF_PASSENGERS" value="1"
Send the request (CalculateExtendedRoute).
Code Samples MAX_WEIGHT, MAX_AXLE_LOAD
Please note the important fact that the free flow speed is a static speed although it is contained in additional dynamic data, and dynamic routing must be enabled. That means also that a route calculated using free flow speeds is a static route.
The common way to calculate dynamic routes is to use FeatureLayer which contain time-dependent data such as traffic patterns or traffic information. There is another way which is deprecated and which we refer to as legacy dynamic routing. Most parameters apply to both ways. For using FeatureLayer more information can be found here.
This section refers to the basic configuration in the property file conf/xroute.properties.
In order to use FeatureLayer, configuration is not necessary. At least one time-dependent layer such as PTV_SpeedPatterns and the PTV_TimeZones layer have to be available in the map folder.
Please do not get confused about the multiple use of the word dynamic. Whereas dynamic routing means the use of time-dependent information, a dynamic FeatureLayer means that the data can be updated during the runtime of PTV xRoute Server.
In order to enable dynamic routing proper data are needed. Please contact your PTV representative to obtain these data.
Then dynamic routing must be enabled in the in the property file conf/xroute.properties:
dynamicParameter.enableDynamic=true
When dynamic routing is enabled, the resulting route will take time-dependent information into account. The resulting route will be the optimal route at this point of time regarding the current traffic situation. It may be different from the static route, and the dynamic travel time will also differ from the static one. The performance may also be affected. Please set the routing start time properly.
In order to enable FeatureLayer, just enable the themes to be used in the XML profile.
In order to enable legacy dynamic set the following API or xRoute profile parameters.
| parameter | description |
|---|---|
|
RoutingParameter ENABLE_DYNAMIC Profile/Routing/Course/DynamicRouting/@useLegacyDynamic |
Switches dynamic routing on or off. |
|
RoutingParameter DYNAMIC_PROFILE Profile/Routing/Course/DynamicRouting/@layerName |
The name of the dynamic data layer. |
There are a lot more use-cases for dynamic routing which all apply to both FeatureLayer and legacy dynamic routing. These parameters will only be interpreted, if dynamic routing is enabled.
| parameter | description |
|---|---|
|
RoutingParameter DYNAMIC_TIME_ON_STATICROUTE Profile/Routing/Course/DynamicRouting/@dynamicTimeOnStaticRoute |
Calculate the dynamic travel time for the static route. This means that the route calculation take place as if dynamic routing was not enabled, so that the resulting route is static. Then the travel time will be calculated taking dynamic information. This is useful when comparing the travel time at the current traffic situation (rush hour or traffic jams) with normal traffic. |
|
RoutingParameter ENABLE_DYNAMIC_WITH_FREE_FLOW_SPEED Profile/Routing/Course/DynamicRouting/@useFreeFlowSpeed |
The static route is calculated using the travel speed information of the map. As these information are obtained by classifying the streets, this model can be inaccurate when comparing static routes to dynamic routes. Therefore dynamic data contain information on the actual travel speed on each street with uncongested traffic, for example at night. This so-called free-flow speed will be used to calculate the static route if this switch is enabled. |
|
RoutingParameter DYNAMIC_TRAVEL_TIME_STEP_SIZE RoutingParameter DYNAMIC_TRAVEL_TIME_STEP_COUNT Profile/Routing/Course/DynamicRouting/DynamicTimeStep/@size Profile/Routing/Course/DynamicRouting/DynamicTimeStep/@count |
Calculate not only one but several dynamic travel times at different points of time on the static route (so-called travel trend). These parameters extend the calculation of the dynamic travel time on the static route above and will only be interpreted if this feature is enabled. The step size given in [min] for the API parameter or in [s] for the XML profile parameter and the step count determine at how many equidistant points of time the dynamic travel time is to be calculated. For commuters this feature is useful to find out the optimal departure time. |
| ResultListOptions dynamicInfo | Enables the calculation of the time benefit of driving around a traffic congestion in contrast to driving through it and the time loss of driving around the traffic congestion in contrast to uncongested traffic. See API documentation for details. |
The following diagram shows the context of these parameters for legacy dynamic (for FeatureLayer RoutingParameter ENABLE_DYNAMIC has to be exchanged by the parameter enableTimeDependency).
The result types in the diagram describe which information will be available for the different options.
Route - The resulting route can be static or dynamic.
times - The times are in the RouteInfo object. They can be static or dynamic.
travel trend - If travel trend for commuters is requested.
dynamic info - The DynamicInfo object if dynamic info is requested. It has additional information about travel time.
CalculateRoute and CalculateExtendedRoute can calculate a static route with dynamic information such as traffic jams or historic traffic data.
A special license file for routing is needed. Please contact your PTV representative.
Set a destination time for the route. How to set it, see see "Set a destination time and calculate a route"
Set the RoutingParameter ENABLE_DYNAMIC.
Set this parameter to true to use dynamic routing.
parameter="ENABLE_DYNAMIC" value="true"
Set the RoutingParameter DYNAMIC_TIME_ON_STATICROUTE.
Set this parameter to true to use dynamic routing on a static route.
parameter="DYNAMIC_TIME_ON_STATICROUTE" value="true"
Set the RoutingParameter DYNAMIC_PROFILE.
Defines the profilename to be used for dynamic routing.
parameter="DYNAMIC_PROFILE" value="YOUR_DYNAMIC_PROFILE_NAME"
Send the request.
The result is a static route. In the object ResultInfo are the dynamic times for this route.
These parameters are valid for legacy dynamic, for FeatureLayer RoutingParameter ENABLE_DYNAMIC has to be exchanged by the parameter enableTimeDependency. We recommend to use XML profile parameters only.
CalculateRoute and CalculateExtendedRoute can calculate a dynamic route with dynamic information. Additional information about travel time can be requested by the ResultListOption dynamicInfo. The additional time information are the time benefit or loss according to the static route.
A special license file for routing is needed. Please contact your PTV representative.
Set a destination time for the route. How to set it see "Set a destination time and calculate a route" .
Set the RoutingParameter ENABLE_DYNAMIC.
Set this parameter to true to use dynamic routing.
parameter="ENABLE_DYNAMIC" value="true"
Set the RoutingParameter DYNAMIC_TIME_ON_STATICROUTE.
Set this parameter to false to use dynamic routing.
parameter="DYNAMIC_TIME_ON_STATICROUTE" value="false"
Set the RoutingParameter DYNAMIC_PROFILE.
Defines the profilename to be used for dynamic routing.
parameter="DYNAMIC_PROFILE" value="YOUR_DYNAMIC_PROFILE_NAME"
Set the ResultListOption dynamicInfo to true to generate optional travel time information
Send the request.
The object DynamicInfo holds additional information about the travel time: The time benefit you will have when taking the dynamic route in contrast to the travel time on the static route including traffic jams. The time loss you will have when taking the dynamic route in contrast to the static route. The distance difference between the dynamic and the static route and some other information.
These parameters are valid for legacy dynamic, for FeatureLayer RoutingParameter ENABLE_DYNAMIC has to be exchanged by the parameter enableTimeDependency. We recommend to use XML profile parameters only.
A commuter likes to know the best departure time for the shortest travel time. CalculateRoute and CalculateExtendedRoute can return these information for a certain route.
The travel time is calculated repeatedly every x minutes. The RoutingParameters DYNAMIC_TRAVEL_TIME_STEP_SIZE defines the number of minutes. The corresponding RoutingParameter DYNAMIC_TRAVEL_TIME_STEP_COUNT is used for the number of intervals.
Therefor ENABLE_DYNAMIC and DYNAMIC_TIME_ON_STATICROUTE must be set to true.
A special license file for routing is needed. Please contact your PTV representative.
Set a destination time for the route. How to set it see "Set a destination time and calculate a route".
Set the RoutingParameter ENABLE_DYNAMIC.
Set this parameter to true to use dynamic routing.
parameter="ENABLE_DYNAMIC" value="true"
Set the RoutingParameter DYNAMIC_TIME_ON_STATICROUTE.
Set this parameter to true to use dynamic routing on a static route.
parameter="DYNAMIC_TIME_ON_STATICROUTE" value="true"
Set the RoutingParameter DYNAMIC_PROFILE.
Defines the profilename to be used for dynamic routing.
parameter="DYNAMIC_PROFILE" value="YOUR_DYNAMIC_PROFILE_NAME"
Set the RoutingParameter DYNAMIC_TRAVEL_TIME_STEP_SIZE.
Set this parameter to the step size in minutes. The START_TIME + DYNAMIC_TRAVEL_TIME_STEP_SIZE has to be in the same day as START_TIME! In this example the step size is 10 minutes and the step count 13. The route will be calculated from the START_TIME 13 times in steps of 10 minutes.
parameter="DYNAMIC_TRAVEL_TIME_STEP_SIZE" value="10"
Set the RoutingParameter DYNAMIC_TRAVEL_TIME_STEP_COUNT.
Set this parameter to the number of intervals.
parameter="DYNAMIC_TRAVEL_TIME_STEP_COUNT" value="13"
Send the request.
The result is a static route. In the object ResultInfo are the dynamic times for this route. The array travelTrend consists of 13 CommuterTravelTrend objects.
These parameters are valid for legacy dynamic, for FeatureLayer RoutingParameter ENABLE_DYNAMIC has to be exchanged by the parameter enableTimeDependency. We recommend to use XML profile parameters only.
Additional geographic data such as points of interest can be used with route calculation. You can search for all objects which are reachable starting from either a certain sink or along a route. Furthermore, the calculation of a route can consider current traffic information such as traffic jams.
The mechanism works as follows. The data in question is imported from a database on the fly and then used immediately when executing the request. For more information on database configuration, filter and routing information see "How to Access Additional Geographic Data".
For a geographic data request you need some geodatasource configuration name, the layer name and the profile name. This information has to be set in the request using the parameter ReachableObjectsOptions geodatasourceLayer. It has to be formatted as follows:
<configuration>.<layername>[.<profile>][;<SQL Filter>].
The component parts are:
<configuration>
The geodatasource configuration name is the part of the filename <configuration>-geodatasource.xml. The layer name and the profile is configured in this file. Here are the first lines of this file:
<?xml version="1.0" encoding="UTF-8"?>
<GeoDatasource majorVersion="1" minorVersion="0"
xmlns="http://www.ptv.de/com/ptvag/xserver/engines/xpoidbaccess"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<Datasource driver="org.apache.derby.jdbc.ClientDriver"
url="jdbc:derby://localhost:50036/poi"
user="POI" password="POI"/>
<Layers default="points-of-interest">
<LayerInfo name="points-of-interest" coordType="PTV_GEODECIMAL" table="T_DATA_POI">
<Profiles>
<Profile name="default" filename="geodata-poi-default.xml"/>
<Profile name="petrol-stations" filename="geodata-petrol-stations.xml"/>
<Profile name="petrol-stations-alternative"
filename="geodata-petrol-stations-alternative.xml"/>
<Profile name="restaurants" filename="geodata-restaurants.xml"/>
</Profiles>
<AttributeMappings>
<AttributeMapping attributeName="ID" columnName="ID" type="int"/>
<AttributeMapping attributeName="X" columnName="X" type="int"/>
<AttributeMapping attributeName="Y" columnName="Y" type="int"/>
<AttributeMapping attributeName="TYPE" columnName="FEATURECODE" type="int"/>
</AttributeMappings>
<layername>
This is the attribute name of the XML element LayerInfo and determines the layer to be used.
<profile>
The configuration can list several profiles under the tag Profiles. This attribute specifies which of these should be referred to. If omitted default is assumed. If the default profile does not exists, the first profile of the profile list is used.
<SQL Filter>
Additionally, an SQL filter statement can also be added. For this SQL filter you can use the column names of the database or attributeNames in brackets (like [TYPE]). These attributeNames are defined in the AttributeMappings of your used LayerInfo in the file <configuration>-geodatasource.xml. With the AttributeMapping columnNames can be mapped to attributeNames. A columnName can only be used once in a AttributeMappings element.
The SQL filter will be attached at the end of the WHERE clause. Valid expressions are comparisons (<, >, =, like, …). Concatenations of expressions are possible with the SQL operators AND and OR.
Using the method searchForReachableObjects() all objects such as restaurants or petrol-stations which are reachable within a certain travel time or distance from a route can be obtained.
Get the binaryPathDescription of your Route
Define the geodatasource configuration name, the layer name and the profile name
Trigger the request
1. Calculate a route
First calculate a route and set the ResultListOptions binaryPathDesc to true to the binary path description. In the binaryPathDesc of the Route result object you can get the binaryPathDesc which you need to call the method searchForReachableObjects().
2. Determine ReachableObjectsOptions GeodatasourceLayer
For this use-case the default configuration with the layer points-of-interests and the profile restaurants should be considered. Therefore geodatasourceLayer must be set to default.points-of-interest.restaurants.
3. Trigger the request
Set binaryPathDesc to the binaryPathDesc of your first Routing result.
Set ReachableObjectsOptions geodatasourceLayer to default.points-of-interest.restaurants.
Send the request.
The result is in the object ReachableObjects.
For this use case you need the information of section Geodatasource configuration. In this use case all restaurants are searched along a route. You can define in which maximum distance in meters the restaurants should be. Also you can define the driving time (in seconds). In this example the restaurants should be in a distance of 4 km.
Set binaryPathDesc to the binaryPathDesc of your first Routing result.
Set ReachableObjectsOptions geodatasourceLayer to default.points-of-interest.restaurants.
Set ReachableObjectsOptions expansionDesc to ExpansionDescription with the values horizons="4000" and expansionType="EXP_DIST". The distance must be given in meters.
Send the request.
The result is in the object ReachableObjects.
In this example you wish to know which ambulance can reach you in the time of 5 minutes.
Set the coords of the WaypointDesc. This WaypointDesc is used as the parameter sink in the method.
Set ReachableObjectsOptions geodatasourceLayer to default.points-of-interest;featurecode=7321.
The format of geodatasourceLayer is <configuration>.<layername>[.<profile>][;<SQL Filter>]. In this example [TYPE]=7321 is the sql filter for all hospitals which are in the database. [TYPE] is the attributeName of the columnName featurecode. For further information see Geodatasource configuration.
Set the horizon of 5 minutes to ReachableObjectsOptions expansionDesc. The ExpansionDescription should have the values horizons="300" and expansionType="EXP_TIME". The time must be given in seconds.
Set the routingDirection of ReachableObjectsOptions to the RoutingDirectionType BACKWARD. All objects which can reach the sink within the given horizon are calculated.
Send the request
The result is in the object ReachableObjects.
The PTV xRoute Server can consider traffic jams when calculating routes, i.e. it calculates a route which avoids traffic jams if a better one exists. For the configuration of when to avoid traffic jams, please refer to the configuration of the GeoDataProfile.
The profile shipped with PTV xRoute Server is configured as follows (the default database contains three traffic jams in Luxembourg). default.traffic blocks one traffic jam, avoids another, and ignores the third. default.traffic.alternative avoids all of them, and default.traffic.absolute avoids one, adds 10 seconds driving time to another one, and ignores the third.
Set RoutingParameter GEODATASOURCE_LAYER to reference a traffic layer. For this example use default.traffic.
Send the request.
If there is a traffic jam along the regular route then the returned route should now circumvent the traffic jam.
This feature is not available with the service methods calculateReachableObjects and calculateIsochrones.
Click here for an example request.
Routes can be calculated with combined transports as via stations. A combined transport can be a ferry or a piggy back station. The PTV xLocate Server is used to find combined transports. It provides the methods findCombinedTransportByLocation() and findObjectByText(). For this example we use the method findCombinedTransportByLocation(). The result will be used to calculate the route.
As an alternative, combined transport IDs can also be retrieved by using a static POI layer with the PTV xMap Server. See the PTV xMap Server usecases for further details.
Use the method findCombinedTransportByLocation() of the PTV xLocate Server to search a combined transport around the given location. The method returns the object ResultCombinedTransport. This result object contains an id, which can be used in the next example for the routing.
Only for maps 2012.1 or newer!
Set the profile to default.
Choose a coordinate format.
Set the coordinate.
It can be helpful to set some ReverseSearchParameters of the ReverseSearchOptions:
ENGINE_TOLERANCE to 160
ENGINE_TARGETSIZE to 20
ENGINE_FILTERMODE to -1
ENGINE_SEARCHRANGE to -1
RESULT_LANGUAGE to GER
Call findCombinedTransportByLocation().
A route with a combined transport has three WaypointDesc objects: Start, destination and a WaypointDesc object in-between start and destination with the combined transport id of the previous example.
Only for maps 2012.1 or newer!
Set the coordinates of the start and destination location of the WaypointDesc.
Set the combinedTransportID of the WaypointDesc. To get the combinedTransportID see the example Use case 6.1: find combined transports by location.
Set the viaType of the WaypointDesc to COMBINED_TRANSPORT.
Note that the attribute coords must be null, if combinedTransportID is set. Otherwise an exception is thrown.
Send the request.
This feature is only available with the service methods calculateRouteInfo, calculateRoute and calculateExtendedRoute.
In general the request element ResultListOptions triggers which result lists will be returned. Some attributes require other attributes to be set. See the notes for the attributes for more information on these dependencies.
Methods like calculateExtendedRoute, calculateTour,and calculateAdvancedTour can additionally trigger country and toll related result lists with the request element CountryInfoOptions
For more information on the different different speed names and types, see here.
In order to obtain speed limits for the route list segments several aspects have to be considered.
The availability in the map used by PTV xRoute Server
PTV standard maps starting with 2012.1 contain speed limits, but usually only some segments carry these information. Please consult the map documentation for information on the availability. Probably speed limits are available only for some network classes, and only explicit speed limits are present. Explicit speed limits mean that there is a sign with this speed limit on the road, in contrast to implicit speed limits for which there is no special sign on the road such as the general speed limit within built-up areas.
The meaning and the influence on the route calculation
The speed limits represent the legal speed limit and are for informational reasons only. The driving speed used by the route calculation will be taken from the speed table which can be defined in the profile or the request.
The format of the condition string
Each segment can have more than one speed limit as there can be more than one sign on the road. As an example, the speed limit can be 100, but 80 on rain. The condition string gives information about the validity of the speed limit. If it is empty, there is no condition. Otherwise it contains a semicolon separated string where the first item represents the category the condition belongs to, the second item contains the condition itself, and the optional third item contains additional information about the condition.
The list of condition strings will be completed in future depending on newly supported conditions by the map. Thus, the client application must be able to treat unknown condition strings.
The following categories are available:
WEATHER the speed limit is valid depending on special weather conditions
DRIVER the speed limit is valid depending on the age of the driver or on how long the driver owns his driving license
The following condition strings are available:
WEATHER;RAIN the speed limit is valid on rain
WEATHER;FOG the speed limit is valid on fog
WEATHER;ICE the speed limit is valid on ice
WEATHER;LOW_VISIBILITY the speed limit is valid on low visibility
DRIVER;HAS_LICENCE_LESS_ONE_YEAR
DRIVER;HAS_LICENCE_LESS_TWO_YEAR
DRIVER;HAS_AGE_UNDER_21
The licensing
Not all speed limits are free of charge. It depends on the map and its data provider whether or not the speed limits are free of charge or up to which network class they are free of charge. Usually major roads such as highways can be used without a special license, whereas for minor roads a special license is needed. To find out please consult the map documentation. To obtain a license for non-free speed limits, please contact your PTV representative.
If the map you use is at least 2012.1 and you get an exception when requesting speed limits, please contact your PTV representative. Probably your map is missing the licensing information
The response always contains those speed limits which are free of charge or match your license. Other speed limits which are available but do not match your license will be filtered. There are two possible reasons for a segment not having a speed limit: Either the map data do not contain a speed limit, or the network class of the segment in question is not covered by your license.
Only for maps 2012.1 or newer!
Set the attribute speedLimits in CountryInfoOptions to true.
Send the request.
Find the speed limits with each RouteListSegment child element speedLimits.
In order to obtain detailed toll costs per country and toll section, use the calculateExtendedRoute method as following.
This can also be used to collect toll distance and costs of normal toll roads and "named" toll roads (like EcoTax in France) separately.
Set the attribute detailedToll in CountryInfoOptions to true.
Set the attribute namedToll in CountryInfoOptions to true.
Set the attribute waypointIndexInTollCostInfo in CountryInfoOptions to true.
Send the calculateExtendedRoute request.
Iterate over all countryInfos in the returned ExtendedRoute object.
Each CountryInfo contains an array of tollCostInfos describing the detailed toll cost for this country
Each TollCostInfo describes details of a toll section. This toll section can be assigned to the way section between the waypoint given by the waypointIndex and the next one.
Sum the toll cost and toll distance per waypointIndex and toll type:
if (tollCostInfo.tollType == TollType.NATIONALSECTIONBASED) {
normalTollCost[tollCostInfo.waypointIndex] += tollCostInfo.tollPrice;
normalTollDistance[tollCostInfo.waypointIndex] += tollCostInfo.tollDistance;
} else if (tollCostInfo.tollType == TollType.NATIONALNAMEDTOLL) {
ecoTaxCost[tollCostInfo.waypointIndex] += tollCostInfo.tollPrice;
ecoTaxCost[tollCostInfo.waypointIndex] += tollCostInfo.tollDistance;
} ...
Please see the following documents for more information.
The general mechanism of applying XML profiles.
All supported elements of the xRoute profile.
The XML schema.
In this section various xRoute-specific tips can be found to avoid pitfalls.
To specify the language, see here.
When using truck attributes, please keep in mind that vehicle parameters stated in the request using the VehicleParameter values will not be considered if the vehicle specific additional data rules are enabled, see VehicleSpecific.
The LinkTypeConfiguration does not select a link type itself, but only configures the behaviour of different link types which have to be stated in the request.
Changing the routingAlgorithm attribute from the Algorithm element can have serious impact on the routing performance and the results, please do not change its value unless you know what you are doing.
In order to obtain correct results, especially when calculating vehicle-dependent results such as toll, emissions, or routes with truck attributes or feature layers, please fill the Vehicle completely. The algorithms use its values to compute the results, and for most use-cases the defaults will not yield the best results. It depends on the data which attributes will be taken into account, e.g. the height above the front axle will be ignored in toll calculation for most countries, but for some it is relevant.
For correct configuration of AdditionalDataRules see here.
When calculating a route with calculateMatrixInfo or PTV xDima Server and the recalculating it using calculateRouteInfo, travel time and distance may differ although the routing parameters are equal. This can have the following technical reasons:
The linking time and distance is not included in the result of calculateMatrixInfo, but calculateRouteInfo takes it into account. Linking distance means the distance as the crow flies from the co-ordinate to the next valid street segment if the start or destination does not match a street segment exactly.
The leveling heuristic behaves differently as with distance matrix calculation all locations are considered to be waypoints whereas a simple route calculation only has two of them.
When using dynamic routing, the dynamic travel time of the start and destination street segment will not be considered for calculateMatrixInfo.
Use viaType VIA_STOP for all waypoints except for start and destination.
Please consult the chapter About Profiles for general information on jobs.
The service methods calculateBulkRouteInfo and calculateMatrixInfo have corresponding start-methods startCalculateBulkRouteInfo and startCalculateMatrixInfo to start the calculation as a job. The corresponding fetch-methods are fetchBulkRouteInfo and fetchMatrixInfo.
During the calculation the current calculation progress can be watched using watchJob. When watching a bulk calculation, this method returns an instance of BulkProgress which contains information on how many routes have already been calculated and how many are remaining. When watching a matrix calculation, this method returns an instance of DistanceMatrixProgress which contains information on how many rows of the matrix have already been calculated and how rows are remaining.
When stopping the currently running job using stopJob the results already calculated at that point of time will be returned by the fetch-method. Routes not yet calculated will be denoted by error code USER_ABORT for calculateBulkRouteInfo an by error code -3211 in the distance matrix.
Copyright © 2024 PTV Logistics GmbH All rights reserved. | Imprint
