GetRouteCostMatrix - Spectrum_Routing_for_Big_Data - 3.0

Description

The GetRouteCostMatrix service calculates the travel time and distances between an array of start and end locations and returns the route that is either the fastest or the shortest. The result determines the total time and distance of the individual routes (the route costs). For example if you input four start points and four end points, a total of 16 routes will be calculated.

HTTP GET URL Format

The following format is used for HTTP GET requests. HTTP GET is used for simple cost calculations where no additional JSON payload is required.

HTTP GET
  /webApp-context/services/databases/dbsource.json?q=routeCostMatrix&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=routeCostMatrix&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 if the list of input points exceeds the limits of the caller’s URL buffer, as well as including priority for road-types.

Query Parameters

This operation takes the following query parameters:

Examples

Cost matrix route with two start and two end points.

http:
  //<server>:<port>/<webApp-context>/services/<databases>/usroutedatabase.json?
  q = routeCostMatrix & startPoints = -73.56565, 40.5545, -73.46565, 40.4545, 
  epsg: 4326 & endPoints = -73.34343, 40.667, -73.14343, 40.267, 
  epsg: 4326 & returnOptimalRoutesOnly = true &
  optimizeBy = distance & distanceUnit = km & timeUnit = min & 
  majorRoads = true & destinationSrs = epsg: 4322 & returnTime = false

Response

{
 "matrix":
 [{
   "startPoint": {
   "type": "Point", 
   "coordinates":
   [
    -73.56567672202618,
    40.554384822358614
   ],
   "crs": { 
    "type": "name", 
    "properties": {
     "name": "epsg:4322"
    }
   }
  },
  "endPoint": { 
   "type": "Point", 
   "coordinates":
   [
    -73.34345711862802,
    40.66688488742393
   ],
   "crs": { 
    "type": "name", 
    "properties": {
     "name": "epsg:4322"
    }
   }
  },
  "distance": 35.268, 
  "distanceUnit": "km
                },
                {
                 " startPoint ":
                 {
                  " type ": " Point ", 
                  " coordinates ":
                  [
                   -73.46567684021008,
                   40.454384834155185
                  ],
                  " crs ":
                  {
                   " type ": " name ", 
                   " properties ":
                   {
                    " name ": " epsg: 4322 "
                   }
                  }
                 },
                 " endPoint ":
                 {
                  " type ": " Point ", 
                  " coordinates ":
                  [
                   -73.34345711862802,
                   40.66688488742393
                  ],
                  " crs ":
                  {
                   " type ": " name ", 
                   " properties ":
                   {
                    " name ": " epsg: 4322 "
                   }
                  }
                 },
                 " distance ": 44.444,
                 " distanceUnit ": " km "
          }
     ]
}

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=routeCostMatrix&startPoints=-73.56565,40.5545,-73.46565,40.4545,epsg:4326&
  endPoints=-14.321600,60.662859,-73.14343,40.267,epsg:4326&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=routeCostMatrix&startPoints=-73.56565,40.5545,-73.46565,40.4545,epsg:4326&
  endPoints=-14.321600,60.662859,-73.14343,40.267,epsg:4326&version=2

Response:

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