GetTravelBoundary - web_services - 23.1

Spectrum Web Services Guide

Product type
Software
Portfolio
Integrate
Product family
Spectrum
Product
Spectrum > Web Services
Version
23.1
Language
English
Product name
Spectrum Technology Platform
Title
Spectrum Web Services Guide
First publish date
2007
Last updated
2024-10-17
Published on
2024-10-17T00:33:46.811413

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 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:
  • 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 Specifies 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 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:

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
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:
  • MPH (miles per hour)
  • KPH (kilometers per hour)
  • MTPS (meters per second)
  • MTPM (meters per minute)
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:
  • Default propagationFactor is 0.16
  • This parameter can also be specified in the POST body. If the same parameter is set in both GET and POST, then the value in POST is considered.
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)"
        }
      ]
    }