EMS : Rank

[ Whereis® API Home ] [ JSON API Home ] [ Services ] [ Route Services ]

Use the rank service if you have a list of locations and want to find which of them is closest to some given point as, for example, when implementing a storefinder. Ranks a list of points based on their proximity to a reference point.

The service accepts a list of points and returns them as <rankedPoint> objects, listed in order of distance from the reference point.

URL

HTTP Post to <ENDPOINT>service/rank

Request format

{
	"startPoint":<point>,
	"tolls":<Boolean>,
	"method":<string>,
    "mode":<string>,
    "endPoints":[{<point>}]
}

Rules

Parameter	Mandatory?	Description
startPoint	Y	Point by reference to which the other points will be ranked
tolls	N	Default = true
method	N	Options are: "FASTEST" - the quickest time "SHORTEST" - the shortest distance "EASIEST" the least amount of turns "NO_FREEWAYS" - quickest time, but with no freeways "AVOID_FREEWAYS" - quickest time, but with fewer freeways "PREFER_FREEWAYS" - quickest time, but with more freeways "IGNORE_PIPES" - special method that ignores turn restrictions Default = "FASTEST" This parameter is ignored in "FOOT" mode.
mode	N	May be "VEHICLE", "FOOT" or "STRAIGHT_LINE"
endPoints	Y	List of <point> objects to be ranked. There must be at least one point in the list.

Sample request

{
   "startPoint":{"lon":100, "lat":-20},
   "tolls":"true",
   "method":"FASTEST",
   "mode":"STRAIGHT_LINE",
   "endPoints":[
      {"lon":100, "lat":-30},
      {"lon":101, "lat":-30}, 
      {"lon":102, "lat":-30}, 
      {"lon":120, "lat":-30}, 
      {"lon":100, "lat":-31}
   ]
}

Sample response

{
  "rankedPoints": [
    {
      "endPoint": {
        "lon": 144.9602,
        "lat": -36.81063
      },
      "distance": 4722391.1,
      "duration": 168656
    },
    {
      "endPoint": {
        "lon": 144.9602,
        "lat": -36.81063
      },
      "distance": 4722391.5,
      "duration": 168656
    },
    {
      "endPoint": {
        "lon": 144.9602,
        "lat": -36.91063
      },
      "distance": 4724473.5,
      "duration": 168731
    },
    {
	  "endPoint": {
        "lon": 145.1602,
        "lat": -36.81063
      },
      "distance": 4739883.3,
      "duration": 169281
    }
  ]
}

NOTES

The number of points you can rank in a single request is limited to 20.

Icon

This request uses the following objects:

<point>
<rankedPoint>