EMS : Ranking

The ranking service lets you rank a set of points by their proximity to some fixed reference point. The ranking may be calculated via the street network or by straight line distance. If ranked via the street network, you can elect whether or not to permit travel by toll roads.

A typical use for ranking is a store finder, used to identify the closest outlet to some entered address.

To rank a list of points, perform the following steps.

1. Initialise the Rank service.
2. Format the request.
3. Submit the request, nominating a callback function.

If the request succeeds, the API returns a list of RankedPoint objects.

    4. Process the response within the callback function.

A successful response contains a list of RankedPoint objects, ordered by proximity to the reference point, which is itself returned at index [0].  Each RankedPoint includes a distance, ranking method, and travel time from your nominated reference point.

Sample Request

The following example shows how a list of known points may be ranked in relation to a reference point and the result retrieved into a callback function

/Initialise service 
var service = new EMS.Service.Rank();
//format request
var query = {
    "start": {lon: 144.6534, lat: -36.5534},
    "points":[{lon: 144.6424, lat: -37.5531}, 
        {lon: 144.3383, lat: -36.3344}],
    "method": EMS.RouteMethod.FASTEST,
    "mode": EMS.RouteMode.VEHICLE,
    "tolls": false
}
//Submit request
service.rank(query,callback); 
//Handle request
function callback(response, status) {
           
    if (status == EMS.Status.OK) {
        // Success
    } else {
        // Failure
        alert(response.message);
    }
});

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