High-performance Routing
This use-case describes how to retrieve meta information about the availability of high-performance networks and then shows how to use this information to calculate a route with high-performance routing networks.
Benefits
- Using the xData API makes it easy to obtain the available high-performance routing networks.
- Using the xRoute API makes it easy to obtain optimized routes based on minimal input.
- Control and information over the routing type.
Prerequisites
Please ensure following prerequisites are fulfilled before you start with the use case:
- Installed PTV xData service
- Installed and licensed PTV xRoute service with an activated license key for highPerformanceRouting
- At least one high-performance routing network
Programming Guide
The listHighPerformanceRoutingNetworks API is very flexible. Three sample applications are shown in the following.
The first sample shows how to select a high-performance routing network for an xroute request. This is especially useful if only a few parameters are relevant for your routing. The list of high-performance routing networks is filtered for networks that allow Luxembourg.
Before calculating a route, we retrieve the information about a high-performance routing network that covers Luxembourg by calling listHighPerformanceRoutingNetworks. The request we pass to calculateRoute for this task contains the list with our two , entities from the high-performance routing network like the and geographic restrictions, the result fields with the route report enabled to retrieve the routing type, and the route options specifying the routing type to high-performance routing. Once xroute has processed the request the callback routingCompleted is invoked accessing the result of the calculation in the form of a RouteResponse object.
xdata.listHighPerformanceRoutingNetworks({"resultFields":{"highPerformanceRoutingNetworkOptions":true,"profiles": true}}, listCompleted);
function listCompleted(response, exception) {
var network;
if (response.highPerformanceRoutingNetworkInformation) {
// search a network that covers Luxembourg
for (var i = 0; i < response.highPerformanceRoutingNetworkInformation.length; i++) {
var current = response.highPerformanceRoutingNetworkInformation[i].highPerformanceRoutingNetworkDescription;
if (current.highPerformanceRoutingNetworkOptions.geographicRestrictions == undefined ||
current.highPerformanceRoutingNetworkOptions.geographicRestrictions.allowedCountries.indexOf("LU") != -1) {
network = current;
break;
}
}
if (!network) {
print("No suitable high-performance routing network available!")
return;
}
} else {
print("Didn't find any high-performance routing networks at all!");
return;
}
var A = {
"$type": "OnRoadWaypoint",
"location": {
"coordinate": {
"x": 6.05813,
"y": 49.55812
}
}
};
var B = {
"$type": "OnRoadWaypoint",
"location": {
"coordinate": {
"x": 6.033751,
"y": 49.542127
}
}
};
xroute.calculateRoute({
"requestProfile": network.profile,
"resultFields": {
"report": true
},
"waypoints": [A, B],
"routeOptions": {
"routingType": "HIGH_PERFORMANCE_ROUTING",
"geographicRestrictions": network.highPerformanceRoutingNetworkOptions.geographicRestrictions,
"timeConsideration": network.highPerformanceRoutingNetworkOptions.timeConsideration
}
},
routingCompleted);
}
function routingCompleted(route, exception) {
print(route.distance + 'm in ' + route.travelTime + 's' + ' with routing type ' + route.report.routingType);
}
The second sample shows how to use listHighPerformanceRoutingNetworks to query whether there is a high-performance routing network available for the current . This integration sample may take a moment as it may create a high-performance routing network in the beginning for demonstration purposes. Of course, this is cleaned up afterwards.
var options = {
"geographicRestrictions": {
"allowedCountries": [
"LU"
]
},
"timeConsideration": {
"$type": "SnapshotTimeConsideration",
"referenceTime": "2015-12-24T12:00:00+01:00"
}
};
var effectiveProfile = {
"routingProfile": {
"course": {
"distanceTimeWeighting": 1
}
}
};
job = xdata.startCreateHighPerformanceRoutingNetwork({
"label": "Luxembourg with default 40t truck, custom distance time weighting and snapshot time consideration",
"storedProfile": "truck40t",
"requestProfile": effectiveProfile,
"highPerformanceRoutingNetworkOptions": options
});
result = waitForJobToFinish(job);
if (result.status == true)
{
id = result.content;
xdata.listHighPerformanceRoutingNetworks({
"storedProfile": "truck40t",
"requestProfile": effectiveProfile,
"returnOnlyMatchingNetworks": true,
"highPerformanceRoutingNetworkOptions": options,
"resultFields": {
"profiles": true,
"highPerformanceRoutingNetworkOptions": true
}
}, listCompleted);
} else if (result.status == false) {
// no-op
} else {
print("Unknown error during high-performance routing network creation.");
}
function listCompleted(response, exception) {
if (response.highPerformanceRoutingNetworkInformation) {
var network = response.highPerformanceRoutingNetworkInformation[0];
print("Found a suitable high-performance routing network with id " + network.highPerformanceRoutingNetworkDescription.id + "! You can use high-performance routing with your current profile!");
if (id) {
xdata.deleteHighPerformanceRoutingNetwork({"id": id});
}
} else {
print("No suitable high-performance routing network available. Consider creating one!");
}
}
function waitForJobToFinish(job, exception) {
do {
job = xdata.watchJob({"id": job.id});
} while (job.status != "SUCCEEDED" && job.status != "FAILED");
try {
fetchResult = xdata.fetchHighPerformanceRoutingNetworkResponse(job.id);
return { "status": true, "content": fetchResult.id};
} catch (e) {
return { "status": false, "content": "" };
}
}
In the third sample it is shown how to use high-performance routing by setting the id of a high-performance routing network.
var A = {
"$type": "OffRoadWaypoint",
"location": {
"offRoadCoordinate": {
"x": 6.1256572,
"y": 49.5983745
}
}
};
var B = {
"$type": "OnRoadWaypoint",
"location": {
"coordinate": {
"x": 6.1256572,
"y": 49.4816576
}
}
};
var options = {
"geographicRestrictions": {
"allowedCountries": [
"LU"
]
},
"timeConsideration": {
"$type": "SnapshotTimeConsideration",
"referenceTime": "2015-12-24T12:00:00+01:00"
}
};
var effectiveProfile = {
"routingProfile": {
"course": {
"distanceTimeWeighting": 1
}
}
};
job = xdata.startCreateHighPerformanceRoutingNetwork({
"label": "Luxembourg with default 40t truck, custom distance time weighting and snapshot time consideration",
"storedProfile": "truck40t",
"requestProfile": effectiveProfile,
"highPerformanceRoutingNetworkOptions": options
});
result = waitForJobToFinish(job);
if (result.status == true)
{
id = result.content;
xroute.calculateRoute({
"waypoints": [A, B],
"routeOptions": {
"routingType": "HIGH_PERFORMANCE_ROUTING",
"highPerformanceRoutingNetworkId": result.content
},
"resultFields": {
"report": true,
}
}, routingCompleted);
} else if (result.status == false) {
// no-op
} else {
print("Unknown error during high-performance routing network creation.");
}
function routingCompleted(route, exception) {
print(route.distance + 'm in ' + route.travelTime + 's' + " with routing type " + route.report.routingType);
if (id) {
xdata.deleteHighPerformanceRoutingNetwork({"id": id});
}
}
function waitForJobToFinish(job, exception) {
do {
job = xdata.watchJob({"id": job.id});
} while (job.status != "SUCCEEDED" && job.status != "FAILED");
try {
fetchResult = xdata.fetchHighPerformanceRoutingNetworkResponse(job.id);
return { "status": true, "content": fetchResult.id};
} catch (e) {
return { "status": false, "content": "" };
}
}
General notes
In this example we provide our waypoints A and B as x, y coordinates in the default EPSG:4326 format (see RequestBase.coordinateFormat). For A and B we use OnRoadWaypoint, see the technical concept on waypoints and route legs for more information on the different waypoints.
Please refer to the documentation of the RouteRequest for more information on request parametrization.
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. networks and then shows how to use this information to calculate a route with high-performance routing networks.