GetTravelBoundary

Description

GetTravelBoundary determines a drive or walk time or distance 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 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 /rest/Spatial/erm/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 Enterprise Routing Module Routing Database Resource tool.

HTTP POST URL Format

The following format is used for HTTP POST requests:

HTTP POST:  /rest/Spatial/erm/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 information and examples on these options, see GetTravelBoundary HTTP POST Options.

Query Parameters

This operation takes the following query parameters.

Examples

Travel boundary with a single cost.

http://<server>:<port>/rest/Spatial/erm/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","coordinates":[[[...]]]}
			}
		]
	}
}

Travel boundary with multiple costs.

http://<server>:<port>/rest/Spatial/erm/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","coordinates":[[[...]]]}"
			},
			{
				"cost": 5,
				"costUnit": "m",
				"geometry": "{"type":"MultiPolygon","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>/rest/Spatial/erm/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>/rest/Spatial/erm/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)"
      }
    ]
  }