GetTravelBoundary - Spectrum_Routing_for_Big_Data - 3.0

Description

GetTravelBoundary determines a drive or walk time or distance of a boundary from a location. This feature obtains polygons corresponding to an isochrone or isodistance calculation. An isochrone is a polygon or set of points representing an area that can be traversed in a network from a starting point in a given amount of time. An isodistance is a polygon or set of points representing the area that is at a certain distance from the starting point. The GetTravelBoundary operation (also known as an iso definition) takes a starting point, a unit (linear or time), one or more costs as input and returns the resulting travel boundary. Costs refer to the amount of time or distance to use in calculating an iso. Multiple costs can also be given as input. In case of multiple costs, costs can also be provided as a comma delimited string.

HTTP GET URL Format

The following format is used for HTTP GET requests. HTTP GET is used for all travel boundaries where no additional JSON payload is required (ambient speed changes).

HTTP GET
  /webApp-context/services/databases/dbsource.json?q=travelBoundary&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=travelBoundary&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 ambient speeds for road types. For more information and examples on these options, see GetTravelBoundary HTTP POST Options.

Query Parameters

This operation takes these query parameters.

Examples

Travel boundary with a single cost.

http://server:port/webApp-context/services/databases/usroutedatabase.json? 
q = travelBoundary & point = -77.092609, 38.871256, epsg: 4326 &
    costs = 5 & costUnit = m

Response

{
 "travelBoundary": { 
  “costs”: [{
    "cost": 5, 
    "costUnit": "m", 
    "geometry": {
      "type": "MultiPolygon", 
      "crs": {
       "type": "name", 
       "properties": {
        "name": "epsg: 4326"
       }
      },
      "coordinates": [ 
       [
        [
         ...
        ]
       ]
      ]
     }
    }
   ]
  }
 }

Travel boundary with multiple costs.

http:
//server:port/webApp-context/services/databases/usroutedatabase.json? 
q = travelBoundary & point = -77.092609, 38.871256, epsg: 4326 & 
    costs = 2, 5 & costUnit = m

Response

{
 "travelBoundary": { 
  "costs": [{
    "cost": 2, 
    "costUnit": "m",
    "geometry": "{" type ":" MultiPolygon "," crs ":{" type ":" name ","
     properties ":{" name ":" epsg: 4326 "}}," coordinates ":[[[...]]]}"
   }, {
    "cost": 5, 
    "costUnit": "m",
    "geometry": "{" type ":" MultiPolygon "," crs ":{" type ":" name ","
     properties ":{" name ":" epsg: 4326 "}}," 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=travelBoundary
       &costs=5&costUnit=min&point=-14.321600,60.662859,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=travelBoundary
       &costs=5&costUnit=min&point=-14.321600,60.662859,epsg:4326&version=2

Response:

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