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.
Parameter | Type | Required | Description |
---|---|---|---|
point | String | Yes | Specifies the start location from where to calculate the travel boundary in the format: x, y, coordSys. For example: -74.2,40.8,epsg:4326 |
costs | Double | Yes | Specifies the cost distance or time, in the cost units specified (can be a decimal value). For example, if the unit specified is miles and you specify 10 in this parameter, the travel boundary will be calculated for how far you can travel 10 miles. You can also specify multiple costs by specifying the values as a comma delimited string. It will return a separate travel boundary for every cost specified. If you specify multiple costs, every response will have cost and cost units associated with that response. |
costUnit | String | Yes | Specifies the type of metric used to calculate the travel boundary. Available distance
values are:
|
maxOffroadDistance | Double | No | The maximum distance to allow travel off the road network using the maxOffroadDistanceUnit. Examples of off-network roads include driveways and access roads. For example, if you specify a maximum off road distance of 1 mile the travel boundary will extend no further than one mile from the network road. If you specify a value of 0 the travel boundary will not extend beyond the road itself. Use the ambient speed options to specify the speed of travel along non-network roads. |
maxOffroadDistanceUnit | String | No | Specifies the distance unit defining the maxOffroadDistance. You
must also define maxOffroadDistance if you define this parameter.
Available distance values are:
|
destinationSrs | String | No | Specifies the coordinate system to return the travel boundary geometries. The default is the coordinate system of the data used (for example, epsg:4326). |
majorRoads | Boolean | No | Specifies whether to include all roads in the calculation or just major roads. If you choose to include only major roads, performance will improve but accuracy may decrease. The default is true. |
returnHoles | Boolean | No | Specifies whether you want to return holes, which are areas within the larger boundary that cannot be reached within the desired time or distance, based on the road network. The default is false. |
returnIslands | Boolean | No | Specifies whether you want to return islands, which are small areas outside the main boundary that can be reached within the desired time or distance. The default is false. |
simplificationFactor | Integer | No | Specifies the percentage of the original points to be returned or upon which the resulting complexity of geometries should be based. A number between 0.0 and 1.0 is accepted, exclusive of 0.0 but inclusive of 1.0. Complexity increases as the value increases, therefore 1.0 means the most complex. The default is 0.5. |
bandingStyle | String | No |
Specifies the style of banding to be used in the result. Banding styles are the types of multiple distance bands that can be displayed based on multiple costs. Banding styles can be returned in the following formats:
|
historicTrafficTimeBucket | String | No |
Specifies whether the routing calculation uses the historic traffic speeds. These speeds are based on different time-of-day buckets. The data must have historic traffic speeds included in order to use this feature. The data for each country/region has the same bucket definitions, where the speeds for these bucket values may vary. The options are:
|
defaultAmbientSpeed | String | No |
Specifies the speed to travel when going off a network road to find the travel boundary
(for all road types). To control how off-network travel is used
in the travel boundary calculation, you need to specify the
speed of travel off the road network (the ambient speed).
Ambient speed can affect the size and shape of the travel
boundary polygon. In general, the faster the ambient speed, the
larger the polygon. For example, if you were at a point with 5
minutes left, and if the ambient speed were 15 miles per hour,
boundary points would be put at a distance of 1.25 miles. If the
ambient speed were reduced to 10 miles per hour, boundary points
would be put at a distance of 0.83 miles.
Note: Default
defaultAmbientSpeed is 15
|
ambientSpeedUnit | String | No |
Specifies the unit of measure to calculate the ambient speed. Available speed units are:
Note: Default ambientSpeedUnit is
MPH
|
propagationFactor | String | No |
Specifies the percentage of the cost used to calculate the distance between the starting point and the isodistance (for all road types). Propagation factor serves the same purpose for isodistances as ambient speed does for isochrones, that is, it controls how off-network travel is used in the travel boundary calculation. Propagation factor can affect the size and shape of the travel boundary polygon. In general, more the propagation factor value, the larger the polygon. It applies to isodistances. If this property is not specified,
then the calculation uses the server setting. Valid values are
between 0.0 and 1.0, both inclusive.
Note:
|
version | String | No | Specifies the version of the GetTravelBoundary REST service. Valid values are 1 and 2. The default value for version is 1. |
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)" } ] }