GetRouteCostMatrix

Description

The GetRouteCostMatrix service calculates the travel time and distances between an array of start and end locations and returns the route that is either the fastest or the shortest. The result determines the total time and distance of the individual routes (the route costs). For example if you input four start points and four end points, a total of 16 routes will be calculated.

Note: The response from the REST service will be in JSON format and the geometry returned will be in GeoJSON 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 simple cost calculations where no additional JSON payload is required.

HTTP GET /rest/Spatial/erm/databases/dbsource.json?q=routeCostMatrix&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 Spectrum Spatial 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=routeCostMatrix&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 if the list of input points exceeds the limits of the caller’s URL buffer, as well as including transient updates, or priority for road-types. For information and examples on these options, see GetRouteCostMatrix HTTP POST Options.

Query Parameters

This operation takes the following query parameters.


Parameter	Type	Required	Description
startPoints	String	Yes	The start locations of the route in the format: long,lat,long,lat,...,coordSys. For example: -74.2,40.8,-73,42,epsg:4326
endPoints	String	Yes	The end locations of the route in the format: long,lat,long,lat,...,coordSys. For example: -74.2,40.8,-73,42,epsg:4326
destinationSrs	String	No	The coordinate system to return the route and resulting geometries. The default is the coordinate system of the data used.
optimizeBy	String	No	The type of optimizing to use for the route. Valid values are `time` or `distance`. The default is time.
returnDistance	Boolean	No	The route directions include the distance traveled. The default is true. Both returnDistance and returnTime parameters cannot be false in the same request.
distanceUnit	String	No	The units to return distance. The default is m (meter). Available values are: m(meter), km(kilometer), yd(yard), ft(foot), mi(mile).
returnTime	Boolean	No	The route directions include the time it takes to follow a direction. The default is true. Both returnDistance and returnTime parameters cannot be false in the same request.
timeUnit	String	No	The units to return time. The default is min (minute). Available values are: min(minute), msec (millisecond), s(second), h(hour).
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 false.
returnOptimalRoutesOnly	Boolean	No	Whether to return only the optimized route for each start point/end point combination. The default is true. The optimized route is either the fastest route or the shortest distance, depending on the `optimizeBy` parameter.
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.
avoid	String	No	Specifies a comma-separated list of road types to be avoided during route calculation. This is a String parameter. When a road type is provided as the value of the parameter, the route excludes that type of roads in route calculation. For example, if tollRoad is provided as the parameter value, the calculated route contains a route without any toll roads.
version	String	No	Specifies the version of the GetRouteCostMatrix REST service. Valid values are 1 and 2. The default value for version is `1`.
localRoadsLoadFactor	String	No	Specifies the number of local roads that can be loaded into memory during route or matrix calculation. The number of roads that can load is directly proportional to the value selected in the parameter where 1 is the minimum and 3 is the maximum value. Valid values can be 1,2, or 3. The default is 1. See Local Roads Load Factorfor a detailed description and impact of the parameter on routing or matrix calculation. Note: The parameter does not accept decimal values.

Examples

Cost matrix route with two start and two end points.

http://<server>:<port>/rest/Spatial/erm/databases/usroutedatabase.json?q=routeCostMatrix&startPoints=-73.56565,40.5545,-73.46565,40.4545,epsg:4326&endPoints=-73.34343,40.667,-73.14343,40.267,epsg:4326&returnOptimalRoutesOnly=true&optimizeBy=distance&distanceUnit=km&timeUnit=min&majorRoads=true&destinationSrs=epsg:4322&returnTime=false

Response

{
	"matrix": [{
		"distance": 35.258,
		"distanceUnit": "km",
		"endPoint": {
			"type": "Point",
			"coordinates": [-73.34345711862802, 40.66688488742393],
			"crs": {
				"type": "name",
				"properties": {
					"name": "epsg:4322"
				}
			}
		},
		"startPoint": {
			"type": "Point",
			"coordinates": [-73.56567672202618, 40.554384822358614],
			"crs": {
				"type": "name",
				"properties": {
					"name": "epsg:4322"
				}
			}
		}
	}, 
	{
		"distance": 41.761,
		"distanceUnit": "km",
		"endPoint": {
			"type": "Point",
			"coordinates": [-73.34345711862802, 40.66688488742393],
			"crs": {
				"type": "name",
				"properties": {
					"name": "epsg:4322"
				}
			}
		},
		"startPoint": {
			"type": "Point",
			"coordinates": [-73.46567684021008, 40.454384834155185],
			"crs": {
				"type": "name",
				"properties": {
					"name": "epsg:4322"
				}
			}
		}
	}]
}

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=routeCostMatrix&startPoints=-73.56565,40.5545,-73.46565,40.4545,epsg:4326&
endPoints=-14.321600,60.662859,-73.14343,40.267,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=routeCostMatrix&startPoints=-73.56565,40.5545,-73.46565,40.4545,epsg:4326&
endPoints=-14.321600,60.662859,-73.14343,40.267,epsg:4326&version=2

Response:

{
  "errors": [
    {
      "errorCode": 5008,
      "userMessage": "Point outside boundaries: (-14.3216,60.662859,0)"
    }
  ]
}