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: The response from the REST service will be in JSON format. When a request contains invalid query parameters in the GET URL or an invalid payload for POST, a cumulative error response will be returned in a JSON array. The value node in the response JSON is deprecated. For error checking, only the errors node should be utilized.

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: 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.
`defaultAmbientSpeed`	String	no	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	The unit of measure to use to calculate the ambient speed. Available speed units are: MPH(miles per hour), KPH(kilometers per hour), MTPS(meters per second), and MTPM(meters per minute) Note: Default ambientSpeedUnit is MPH

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","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","coordinates":[[[...]]]}"
	},
	{
		"cost": 5,
		"costUnit": "m",
		"geometry": "{"type":"MultiPolygon","coordinates":[[[...]]]}"
	}
  ]
}
}
}