Calculating a Route

This use-case describes how to calculate basic information on a routeA 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. from a point A to B via C as well as how to adjust the request to receive additional information like the route and elevation information.

Benefits

Prerequisites

Please ensure following prerequisites are fulfilled before you start with the use case:

Programming Guide

The PTV xServer offers both a Web serviceA web service represents a communication technology applied in computer networks. It provides an interface described in a machine-processable format, for example WSDL. and a RESTREST (Representational State Transfer) represents a World Wide Web paradigm, consisting of constraints to the design of components which results in a better performance and maintainability. API for calculating routes.

Calculating a route with the web service API

The most basic functionality of xroute is calculating the distance and traveltime from a given point A to a given point B. In the example below we perform this operation using the JavaScript bindings to the xroute API:

var A = { "$type": "OffRoadWaypoint", "location": { "offRoadCoordinate": {"x": 6.1256572, "y": 49.5983745 } } }; var B = { "$type": "OnRoadWaypoint", "location": { "coordinate": {"x": 6.1256572, "y": 49.4816576 } } }; xroute.calculateRoute({ "waypoints" : [A, B] }, routingCompleted); function routingCompleted(route, exception) { print(route.distance + 'm in ' + route.travelTime + 's'); }

In this example we provide our waypointsA waypoint is a geographic location used to specify start, destination and possible stopovers for a route. A and B as x, y coordinates in the default EPSG:4326 format (see RequestBase.coordinateFormat). For A we use an OffRoadWaypoint and for B an OnRoadWaypoint, see the technical concept on waypoints and route legs for more information on the different waypoints. The request we pass to calculateRoute for this task contains just the list with our two waypoints. Once xroute has processed the request the callback routingCompleted is invoked which gives us access to the result of the calculation in the form of a RouteResponse object. As we did not specify a specific vehicleThe 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. profileA 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. (see Vehicle Parametrization) the default one for a 40 ton truck was used.

For many applications knowing only the distance and time traveled is not sufficient. You can selectively enable the calculation of additional information in your request to fit it to your application.

The example below shows some more sophisticated features for a route from A to B via C. For input waypoint A it uses the flag considerAlternativeNearByRoads to avoid using the wrong lane of a highway for a location provided by a GPS device. For the via input waypoint C it uses the ManipulateRouteWaypoint to pass by a location within a radius of 1 km. Finally, the calculation of a polylineA polyline is a continuous line composed of one or more line segments given as a set of tuples with x,y and optional z coordinates. with additional elevation data is requested for the :

var A = { "$type": "OnRoadWaypoint", "location": { "coordinate": {"x":6.1561739444732675,"y":49.581704333851874}, "considerAlternativeNearByRoads": true } }; var B = { "$type": "OnRoadWaypoint", "location": { "coordinate": {"x": 6.1256572, "y": 49.4816576 } } }; var C = { "$type": "ManipulateRouteWaypoint", "coordinate": {"x": 6.3256572, "y": 49.5516576 }, "radius": 1000 }; var map = new L.Map('map', { center: [49.61, 6.125], zoom: 13 }); // Add tile layer to map var tileUrl = xServerUrl + '/services/rest/XMap/tile/{z}/{x}/{y}'; var tileLayer = new L.TileLayer(tileUrl, { minZoom: 3, maxZoom: 18, noWrap: true }).addTo(map); xroute.calculateRoute({ "waypoints" : [A, C, B], "resultFields" : { "polyline" : true }, "routeOptions" : { "polylineOptions" : { "elevations" : true } } }, routingFinished); function displayPolyline(poly) { var polyline = []; for(var i = 0; i < poly.length;++i) { polyline.push(L.latLng(poly[i].y, poly[i].x)); } polylineLayer = L.polyline(polyline, { color: '#2882C8', weight: 8 }); polylineLayer.addTo(map); map.fitBounds(polylineLayer.getBounds()); }; function routingFinished(route, exception) { var polyline = route.polyline.plain.polyline; displayPolyline(polyline); print(route.distance + 'm in ' + route.travelTime + 's starting at ' + polyline[0].z + 'm elevation'); }

All that is needed for the polyline is requesting the corresponding ResultField to be provided. As the elevation data is an optional element of the returned polyline it is configured in the PolylineOptions instead of a separate field in the results.

By default the polyline will be returned as a plain Polyline object consisting of a list of Coordinate objects each of which has x, y and an optional z elevation. The elevation is given as meters above the mean sea level (EGM96) independent of the requested coordinate format.

Another standard task is to avoid toll roads. This feature is contained in the basic xroute license. To do so set the tollPenalty in the RequestProfile to a value greater than 0 and smaller then 2501. For further toll related information see the chapter toll calculation.

For a more complete example of what can be achieved by combining basic routing information, polylines and elevations you can take a look at the Visualize Elevations Sample.

Please refer to the documentation of the RouteRequest for more information on request parameterization.

Calculating a route with the REST API

http://hostname:50000/services/rest/XRoute/experimental/route/{startX}/{startY}/{destinationX}/{destinationY}

In addition to a start and destination location, the results can be further refined by specifying query parameters:

var startX = 6.1256572; var startY = 49.5983745; var destinationX = 6.1256572; var destinationY = 49.4816576; var restPath = xServerUrl + '/services/rest/XRoute/experimental/route/' + startX + '/' + startY + '/' + destinationX + '/' + destinationY + '?polyline=true'; // We use jQuery to send the request. Be sure to reference jQuery for this to work. $.ajax(restPath).always(function(response) { // The request is expected to return a response of type RouteResponse. if (response) { print(response.distance + 'm in ' + response.travelTime + 's'); } else { print('Request did not succeed.'); } });

Please refer to the documentation of the route REST operation for more information on request parameterization.