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