GetRoute - Spectrum_Routing_for_Big_Data - 3.0

Description

The GetRoute service returns routing information for a set of two distinct points or multiple points. It takes a starting location and an ending location with optional intermediate points as input, and returns the route that is either the fastest or the shortest.

HTTP GET URL Format

The following format is used for HTTP GET requests. HTTP GET is used for simple routes where no additional JSON payload is required. Intermediate points can also be added to the HTTP GET request.

HTTP GET
  /webApp-context/services/databases/dbsource.json?q=route&query_parameters

Where: dbsource is the name of the database that contains the data to use for the route. Use the database name specified in the database resource file (dbList.json file). webApp-context is the endpoint to your web application or service. If you are using the default database specified in the database resource file, use default.json in the REST URL for dbsource.

HTTP POST URL Format

The following format is used for HTTP POST requests:

HTTP POST:
  /webApp-context/services/databases/dbsource.json?q=route&query_parameters 
POST BODY: Content-Type:application/json {Route Data}

Route Data is the POST json body (Content-Type: application/json) for the additional route information to be used in the calculation containing intermediate points or priority for road types. For information and examples on these options, see GetRoute HTTP POST Options.

Query Parameters

This operation takes the following query parameters.

Examples

Simple Route with start and end points.

http:
//server:port/webApp-context/services/databases/usroutedatabase.json? q = route & 
  startPoint=-73.97, 40.79, epsg:4326 & endPoint=-73.98, 40.74, epsg:4326

Response

{
 "time": 7.67,
 "timeUnit": "min", 
 "distance": 8865, 
 "distanceUnit": "m"
}

Route with intermediate points.

http:
//server:port/webApp-context/services/databases/usroutedatabase.json? q = route &
  startPoint = -73.970257, 40.794045, epsg: 4326 & endPoint = -73.972103, 40.786605, 
  epsg: 4326 &
  intermediatePoints = -73.976266, 40.788717, -73.973562, 40.792193, -73.971802, 40.794630,
  epsg: 4326 & oip = true & returnIntermediatePoints = true

Response

"intermediatePoints": { "type": "MultiPoint", "coordinates": [
  [-73.971802, 40.79463],
  [-73.973562, 40.792193],
  [-73.976266, 40.788717]
 ]
}

Route with directions enabled.

http:
//server:port/webApp-context/services/databases/usroutedatabase.json? 
q = route & startPoint = -73.97, 40.79, epsg: 4326 & endPoint = -73.98, 40.74,
epsg: 4326 & language = en & directionsStyle = Normal & returnDirectionGeometry = true

Response

{
  "time": 10.58,
  "timeUnit": "min", 
  "distance": 9035, 
  "distanceUnit": "m",
  "language": "en", 
  "directionsStyle": "Normal", 
  "routeDirections": [
  {
   "time": 0.03,
   "timeUnit": "min", 
   "distance": 25, 
   "distanceUnit": "m",
   "instruction": "", 
   "directionGeometry":
   {
    "type": "LineString", 
    "coordinates": [[[...]]]
   }
  },
  {
   "time": 0.7,
   "timeUnit": "min", 
   "distance": 394, 
   "distanceUnit": "m",
   "instruction": "Turn right on W 91st St and travel West 394.0 m (0.7 min).",
   "directionGeometry":
   {
    "type": "LineString",
    "coordinates": [[[...]]]
    ]
   }
  },
  {
   "time": 0.37,
   "timeUnit": "min", 
   "distance": 352, 
   "distanceUnit": "m", 
   "instruction": "Turn left on Broadway and travel Southwest 352.0 m (0.4 min).", 
   "directionGeometry": 
   { 
    "type": "LineString", 
    "coordinates": [[[...]]] 
   } 
  } 
 ] 
}

Version specific error response

When you enter an invalid parameter value (for example, points falling outside of the boundaries) in a request, the error response you get depends on the version entered by you. When the version is 1, you get value and error whereas when the version is 2, the response only contains the error.

Request when version is 1:

http://server:port/webApp-context/services/databases/usroutedatabase.json?
  &q=route&startPoint=-14.321600,60.662859,epsg:4326&endPoint=-74.035208,40.695624,
  epsg:4326&distanceUnit=km&version=1

Response:

{
 "value": "Point outside boundaries: (-14.3216,60.662859,0)", 
 "errors": [
    {
     "errorCode": 5008,
     "userMessage": "Point outside boundaries: (-14.3216,60.662859,0)"
    }
  ]
}

Request when version is 2:

http://server:port/webApp-context/services/databases/usroutedatabase.json?
  &q=route&startPoint=-14.321600,60.662859,epsg:4326&endPoint=-74.035208,40.695624,
  epsg:4326&distanceUnit=km&version=2

Response:

{
 "errors": [
    {
     "errorCode": 5008,
     "userMessage": "Point outside boundaries: (-14.3216,60.662859,0)"
    }
  ]
}