dojo.require("esri.tasks.route");
Description
(Added at v1.4)
The ArcGIS JavaScript API's RouteTask allows you to find routes between two or more locations and optionally get driving directions. The RouteTask uses ArcGIS Server network analysis services to calculate routes. Network analysis services allow you to solve simple routing problems as well as complex ones that take into account multiple stops, barriers, and time windows.
NOTE: For a more updated approach to working with directions, please see the Working with the Directions Widget topic. This widget encompasses routing functionality that used to only be available via the RouteTask. It now takes much of this functionality and wraps it up into a widget making it easier to consume and use.
The following links provides additional information:
The basic pattern to work with this task is:
- Create the task
- Configure the parameters
- Solve the route and then specify what to do with its results and handle any errors that may be returned.
Samples
Search for
samples that use this class.
Constructors
Properties
url | String | URL to the ArcGIS Server REST resource that represents a network analysis service. |
Methods
Events
[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.
Events
error | {
error: <Error >
} | Fires when an error occurs when executing the task. |
solve-complete | {
result: <Object >
} | Fires when RouteTask.solve() has completed. |
Constructor Details
Creates a new RouteTask object.
Parameters:
<String > url |
Required |
URL to the ArcGIS Server REST resource that represents a network analysis service. To obtain the URL, use Services Directory. |
Sample:
var routeTask = new esri.tasks.RouteTask("https://route.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World");
Property Details
URL to the ArcGIS Server REST resource that represents a network analysis service. To obtain the URL, use
Services Directory.
Method Details
Returns an object describing a Route service endpoint (URL of the endpoint is specified in the constructor). The description contains information about the default solver settings, underlying network dataset, available cost and restriction attributes, supported travel modes, etc. If the targeted Network Analyst Server is federated with a Portal or ArcGIS Online, the returned
supportedTravelModes
array will include user-specific travel modes. If the Network Analyst Server works in a standalone configuration, the
supportedTravelModes
will come from the original Closest Facility service description.
A few properties returned in this object include: attributeParameterValues
, impedance
, restrictUTurns
, restrictions
, supportedTravelModes
, travelDirection
, and useHierarchy
.
(Added at v3.14)
Solves the route against the route layer with the route parameters.
Parameters:
<RouteParameters > params |
Required |
Route parameters used as input to generate the route. |
<Function > callback |
Optional |
The function to call when the method has completed. The arguments in the function are the same as the onSolveComplete event. |
<Function > errback |
Optional |
An error object is returned if an error occurs during task execution. |
Sample:
var routeParams = new esri.tasks.RouteParameters();
routeParams.stops = new esri.tasks.FeatureSet();
routeParams.returnRoutes = false;
routeParams.returnDirections = true;
routeParams.directionsLengthUnits = esri.Units.MILES;
routeParams.outSpatialReference = new esri.SpatialReference({ wkid:102100 });
dojo.connect(routeTask, "onSolveComplete", showRoute);
Event Details
[ On Style Events | Connect Style Event ]
Fires when an error occurs when executing the task. Should be used in favor of onError. (Added at v3.5)
Fires when RouteTask.solve() has completed. Should be used in favor of onSolveComplete. (Added at v3.5)
Event Object Properties:
<Object > result |
See the object specifications table below for properties of the result object. |
Object Specifications: <result
>
<Graphic[] > barriers |
Array of graphics representing the polyline barriers. Barriers are returned only if RouteParameters.returnBarriers is true. For the list of attributes returned for each barrier, see the documentation on barriers. |
<NAMessage[] > message |
Message received when solve is completed. If a route cannot be solved, the message returned by the server identifies the route that could not be solved. |
<Graphic[] > polygonBarriers |
Array of graphics representing the polygon barriers. Barriers are returned only if RouteParameters.returnBarriers is true. |
<Graphic[] > polylineBarriers |
Array of graphics representing the polyline barriers. Barriers are returned only if RouteParameters.returnBarriers is true. |
<RouteResult[] > routeResults |
Array of route results. |
Sample:
function showRoute(evt) {
var solveResult = evt.result;
var routeResults = solveResult.routeResults;
var barriers = solveResult.barriers;
var polygonBarriers = solveResult.polygonBarriers;
var polylineBarriers = solveResult.polylineBarriers;
var messages = solveResult.messages;
...
}
Fires when an error occurs when executing the task.
Fires when RouteTask.solve() has completed.
Event Object Properties:
<Object > solveResults |
The result object contains the following properties:
<RouteResult[]> routeResults
|
Array of route results.
|
<Graphic[]> barriers
|
Array of graphics representing the barriers. Barriers are returned only if RouteParameters.returnBarriers is true. For the list of attributes returned for each barrier, see the "Barrier properties" section in Finding the best route.
|
<Graphic[]> polygonBarriers
|
Array of graphics representing the polygon barriers. Barriers are returned only if RouteParameters.returnPolygonBarriers is true.
|
<Graphic[]> polylineBarriers
|
Array of graphics representing the polyline barriers. Barriers are returned only if RouteParameters.returnPolylineBarriers is true.
|
<NAMessage[]> message
|
Message received when solve is completed. If a route cannot be solved, the message returned by the server identifies the route that could not be solved.
|
|
Sample:
function showRoute(solveResult) {
var routeResults = solveResult.routeResults;
var barriers = solveResult.barriers;
var polygonBarriers = solveResult.polygonBarriers;
var polylineBarriers = solveResult.polylineBarriers;
var messages = solveResult.messages;
...
}