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: Response from REST service will be in JSON format and the geometry returned will be in GeoJSON format

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 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=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.
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.
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.

Examples

Simple Route with start and end points.


http://www.pb.com/rest/Spatial/erm/databases/usroutedatabase.json?q=route&startPoint=-73.97,40.79,epsg:4326&endPoint=-73.98,40.74,epsg:4326			
			

Response


{
  "time": 7.67,
  "timeUnit": "min",
  "distance": 8865,
  "distanceUnit": "m"
}			
			

Route with intermediate points.


http://www.pb.com/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			
			

Route with directions enabled.


http://www.pb.com/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			
			

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": ""
    },
    {
      "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)."
    },
    {
      "time": 0.37,
      "timeUnit": "min",
      "distance": 352,
      "distanceUnit": "m",
      "instruction": "Turn left on Broadway and travel Southwest 352.0 m (0.4 min)."
    },
    {
      "time": 0.32,
      "timeUnit": "min",
      "distance": 173,
      "distanceUnit": "m",
      "instruction": "Turn right on Broadway and travel South 173.0 m (0.3 min)."
    },
    {
      "time": 0.23,
      "timeUnit": "min",
      "distance": 330,
      "distanceUnit": "m",
      "instruction": "Turn left on W 34th St and travel East 330.0 m (0.2 min)."
    },
    {
      "time": 0,
      "timeUnit": "min",
      "distance": 1,
      "distanceUnit": "m",
      "instruction": "Turn left to reach your destination to the North."
    }
  ]
}