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.
Parameter | Type | Required | Description |
---|---|---|---|
point | String | yes | 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 | 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 | The type of metric used to calculate the travel boundary. Available distance values are: m(meter), km(kilometer), yd(yard), ft(foot), mi(mile). Available time values are: min(minute), msec(millisecond), s(second), h(hour). |
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 | The distance unit defining the maxOffroadDistance. You must also define maxOffroadDistance if you define this parameter. Available distance values are: m(meter), km(kilometer), yd(yard), ft(foot), mi(mile). |
destinationSrs | String | no | 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 | 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 | What percentage of the original points should 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 |
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:
|
Examples
Travel boundary with a single cost.
http://www.pb.com/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","crs":{"type":"name","properties":{"name":"epsg: 4326"}},"coordinates":[[[...]]]}
}
]
}
}
Travel boundary with multiple costs.
http://www.pb.com/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","crs":{"type":"name","properties":{"name":"epsg: 4326"}},"coordinates":[[[...]]]}"
},
{
"cost": 5,
"costUnit": "m",
"geometry": "{"type":"MultiPolygon","crs":{"type":"name","properties":{"name":"epsg: 4326"}},"coordinates":[[[...]]]}"
}
]
}
}