GetRoute

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.

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

sq
Return directions in Albanian.
zh_CN
Return directions in Chinese.
zh_TW
Return directions in Chinese (Taiwan).
hr
Return directions in Croatian.
cs
Return directions in Czech.
da
Return directions in Danish.
nl
Return directions in Dutch.
en
Return directions in English. Default
en-US
Return directions in American English.
et
Return directions in Estonian.
fi
Return directions in Finnish.
fr
Return directions in French.
de
Return directions in German.
hu
Return directions in Hungarian.
it
Return directions in Italian.
ja
Return directions in Japanese.
lv
Return directions in Latvian.
lt
Return directions in Lithuanian.
no
Return directions in Norwegian.
pt
Return directions in Portuguese.
ro
Return directions in Romanian.
sk
Return directions in Slovak.
sl
Return directions in Slovenian.
es
Return directions in Spanish.
sv
Return directions in Swedish.
ru
Return directions in Russian.
tr
Return directions in Turkish.
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:

None
No directions returned. Default, if not specified.
Normal
Directions are returned in a full format, appropriate for web-based applications.
Terse
Directions are returned in a short format, appropriate for mobile applications.
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:

None
No geometric representation of a segment will be returned. Default, if not specified.
End
Each segment of the route will be returned with just its endpoints in a LineString.
All
Each segment will be returned with all its shape points as a LineString. The LineString can be used as an overlay on a map.
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:

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