EMS : Routing

The routing service performs all route related functions, such as calculating a route, calculating alternate routes and optimising waypoints.

Calculating a route

The route() function on the Route Service returns a route object, containing directions for travel between two or more points. This includes textual step by step directions, the distance and duration of a route and of each segment from one route manoeuvre to the next, and the complete geometry for the full route line and for each of its segments.

To retrieve a route object, perform the following steps.

1. Initialise the Route service.
2. Format the request. This may be passed in as a simple list of two or more waypoints, or as a more complex request object as described in the JSON API.
3. Submit the request, nominating a callback function.

If the request succeeds, the API returns a route object.

1. Process the response within the callback function.

A successful response contains a single route object. Each route contains one or more legs (from waypoint to waypoint), which contain one or more segments (from manoeuvre to manoeuvre).

Sample Request

var service = new EMS.Service.Route();

var waypoints = [];
waypoints.push({"lon": 144.965601, "lat": -37.81125}); 
waypoints.push({"lon": 144.278528, "lat": -36.759366}); 
waypoints.push({"lon": 151.206927, "lat": -33.870246}); 

var query = {
    waypoints: waypoints,                               
    tolls: false,
    method: EMS.RouteMethod.FASTEST,
    mode: EMS.RouteMode.VEHICLE        
}
    
service.route(query, callbackFunction);

Route Response

Some of the route object's significant properties are set out below.

Once generated, the route is stored by the EMS JavaScript API for approximately 30 minutes, and its geometry may be plotted onto or cleared from an existing map object, using the following methods.

Calculating Alternate Routes

Use the altRoutes() function on the Route Service to calculate up to three alternate routes for an existing specified route. The alternate routes will have the same options as the existing route (e.g. vehicle, fastest, no tolls), but will deviate from it based on an allowable percentage difference. This service will return complete routes with geometry. The system will not store cached copies of alternate routes

Sample Request

var service = new EMS.Service.Route();
 
var altOptions = { 
    "id":"KZQUERTY", 
    "count":2
};

service.altRoutes(altOptions, callbackFunction);

Alternate Routes Response

An alternate routes response is simply a list of route objects as described above, although the route handles will not be populated for alternate routes. For more information refer to Alternate Routes in the JSON API

Optimising Waypoints

Use this function to calculate the lowest cost order for a series of waypoints, given an origin (startPoint) and a destination (endPoint). The cost is either distance or time depending on route mode and method. Returns the waypoints reordered in optimal form. Note that different route modes and methods may return different results.

Sample

var service = new EMS.Service.Route();

var startPoint = {"lon": 144.965601, "lat": -37.81125};
var endPoint = {"lon": 151.206927, "lat": -33.870246};
var waypoints = [];
waypoints.push({"lon": 145.278528, "lat": -37.959366}); 
waypoints.push({"lon": 144.278528, "lat": -36.759366}); 

var query = {
    startPoint: startPoint,
    endPoint:endPoint,
    waypoints: waypoints,                               
    tolls: false,
    method: EMS.RouteMethod.FASTEST,
    mode: EMS.RouteMode.VEHICLE        
}
    
service.optimiseWaypoints(query, callbackFunction);

Optimise Waypoints Response

The optimise waypoints response contains the start and end points, the reordered waypoints, a list representing the new waypoint order and a constructed route request that may be used to generate a route. For more information about the optimise waypoints response, refer to Waypoints in the JSON API

Full details of request and response object parameters are set out in the JSON API.