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.

Note: Response from REST service will be in JSON format.

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
cost 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 no 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 Integer 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 where 0.0 is very simple and 1.0 means the most complex. If the specified value is less than 0.0 then 0.0 is assumed while if the specified value is greater than 1.0 then 1.0 is assumed. 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:

Donut
Each boundary is determined by subtracting out the next smallest boundary. This is the default method.
Encompassing
Each boundary is determined independent of all others.
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:

None
The default value. Historic traffic data is not used in the calculation. Instead an averaged speed value is used.
AMPeak
Calculate routes with the peak AM speeds. The AMPeak time bucket is from 07:00 to 10:00hr time of day.
PMPeak
Calculate routes with the peak PM speeds. The PMPeak time bucket is from 16:00 to 19:00hr time of day.
OffPeak
Calculate routes with the off peak (daytime) speeds. The OffPeak time bucket is from 10:00 to 16:00hr time of day.
Night
Calculate routes with the nighttime speeds. The Night time bucket is from 22:00 to 04:00hr time of day.

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":[[[...]]]}"
	}
  ]
}
}