Description
The GetRoute service returns routing information for a set of two distinct points or multiple points. It takes a starting location and an ending location with optional intermediate points as input, and returns the route that is either the fastest or the shortest.
HTTP GET URL Format
The following format is used for HTTP GET requests. HTTP GET is used for simple routes where no additional JSON payload is required. Intermediate points can also be added to the HTTP GET request.
HTTP GET /rest/Spatial/erm/databases/dbsource.json?q=route&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=route&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 intermediate points, transient updates, or priority for road types. For information and examples on these options, see GetRoute HTTP POST Options.
Query Parameters
This operation takes the following query parameters.
Parameter | Type | Required | Description |
---|---|---|---|
startPoint | String | Yes | The start location of the route in the format: x,y,coordSys. For example: -74.2,40.8,epsg:4326 |
endPoint | String | Yes | The end location of the route in the format: x,y,coordSys. For example: -74.2,40.8,epsg:4326 |
intermediatePoints | String | No | A list of intermediate points to include along the route. To include in the HTTP GET request, use the format: Long,Lat,Long,Lat,…,coordsys. For example: -74.2,40.8,-73,42,epsg:4326. To include a set of intermediate points in a HTTP POST request, add the MultiPoint JSON payload indicating the points that the route will include. If intermediate points are specified both in the URL and in the json payload, the json payload is given preference, and the intermediate points in URL are ignored. |
oip | Boolean | No | A processing parameter that indicates if the intermediate points should be optimized. The default is false. By default the intermediate points will be used in the calculation in the order specified. If set to true, the specified points will be re-ordered in an optimal manner during route computation. |
returnIntermediatePoints | Boolean | No |
Whether to return the intermediate points with the route response. The default is false. For any value other that true or false, it will default to false. This option will return the intermediate points in order as specified in the POST body. If the value of option oip is set to true, then this option will return intermediate points in optimized order. |
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. |
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. |
timeUnit | String | No | The units to return time. The default is min (minute). Available values are: min(minute), msec (millisecond), s(second), h(hour). |
language | String | No |
The language the travel directions should be returned, only if route directions are returned (if directionsStyle is defined as Normal or Terse). The default being English (en). Directions can be returned in the following languages:
|
returnDirectionGeometry | Boolean | No | Include the geometry associated with each route instruction in route response. The default is false. |
directionsStyle | String | No |
The type of route directions to return. Default value is None. Specify this parameter if you required route directions to be returned. The options when specifying route directions are:
|
segmentGeometryStyle | String | No |
The format of the geometry that represents a segment of the route. Default value is None. Specify this parameter if you required segment geometries to be returned. The options when specifying route directions are:
|
primaryNameOnly | Boolean | No | Whether to return all names for a given street in the directions or to return just the primary name for a street. Only used when route directions are returned. The default being false. |
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. |
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 GetRoute 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 Factor for a detailed description and impact of the parameter on routing or matrix calculation. Note: The parameter does not accept decimal values.
|
Examples
Simple Route with start and end points.
http://<server>:<port>/rest/Spatial/erm/databases/usroutedatabase.json?
q=route&startPoint=-73.97,40.79,epsg:4326&endPoint=-73.98,40.74,epsg:4326
Response
{
"distance": 7779,
"distanceUnit": "m",
"time": 16.75,
"timeUnit": "min"
}
Route with intermediate points.
http://<server>:<port>/rest/Spatial/erm/databases/usroutedatabase.json?
q=route&startPoint=-73.970257,40.794045,epsg:4326&endPoint=- 73.972103,40.786605,
epsg:4326&intermediatePoints=-73.976266,40.788717,-73.973562,40.792193,-73.971802,40.794630,
epsg:4326&oip=true&returnIntermediatePoints=true"/>
Response
{
"distance": 1921,
"distanceUnit": "m",
"intermediatePoints": {
"type": "MultiPoint",
"coordinates": [
[-73.971802, 40.79463],
[-73.973562, 40.792193],
[-73.976266, 40.788717]
]
},
"time": 4.2,
"timeUnit": "min"
}
Route with directions enabled.
http://<server>:<port>/rest/Spatial/erm/databases/usroutedatabase.json?
q=route&startPoint=-73.97,40.79,epsg:4326&endPoint=-73.98,40.74,
epsg:4326&language=en&directionsStyle=Normal&returnDirectionGeometry=true
Response
{
"time": 10.58,
"timeUnit": "min",
"distance": 9035,
"distanceUnit": "m",
"language": "en",
"directionsStyle": "Normal",
"routeDirections": [
{
"time": 0.03,
"timeUnit": "min",
"distance": 25,
"distanceUnit": "m",
"instruction": "",
"directionGeometry":
{
"type": "LineString",
"coordinates":
[
[
-76.421169,
42.69302
],
[
-76.421353,
42.692645
],
...
]
}
},
{
"time": 0.7,
"timeUnit": "min",
"distance": 394,
"distanceUnit": "m",
"instruction": "Turn right on W 91st St and travel West 394.0 m
(0.7 min).",
"directionGeometry":
{
"type": "LineString",
"coordinates":
[
[
-76.429896,
42.67153
],
...
]
}
}
]
}
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=route&startPoint=-14.321600,60.662859,epsg:4326&endPoint=-74.035208,40.695624, epsg:4326&distanceUnit=km&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=route&startPoint=-14.321600,60.662859,epsg:4326&endPoint=-74.035208,40.695624, epsg:4326&distanceUnit=km&version=2
- Response:
{ "errors": [ { "errorCode": 5008, "userMessage": "Point outside boundaries: (-14.3216,60.662859,0)" } ] }