Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: RouteTask

require(["esri/tasks/RouteTask"], function(RouteTask) { /* code goes here */ });

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:

  1. Create the task
  2. Configure the parameters
  3. 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

NameSummary
new RouteTask(url)Creates a new RouteTask object.

Properties

NameTypeSummary
urlStringURL to the ArcGIS Server REST resource that represents a network analysis service.

Methods

NameReturn typeSummary
getServiceDescription()ObjectReturns an object describing a Route service endpoint (URL of the endpoint is specified in the constructor).
solve(params, callback?, errback?)DeferredSolves the route against the route layer with the route parameters.

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

NameEvent ObjectSummary
error
{
  error: <Error>
}
Fires when an error occurs when executing the task.
solve-complete
{
  result: <Object>
}
Fires when RouteTask.solve() has completed.
Constructor Details

new RouteTask(url)

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:
require([
  "esri/tasks/RouteTask", ... 
], function(RouteTask, ... ) {
  var routeTask = new RouteTask("https://route.arcgis.com/arcgis/rest/services/World/Route/NAServer/Route_World");
  ...
});
Property Details

<String> url

URL to the ArcGIS Server REST resource that represents a network analysis service. To obtain the URL, use Services Directory.
Method Details

getServiceDescription()

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)
Return type: Object

solve(params, callback?, errback?)

Solves the route against the route layer with the route parameters.
Return type: Deferred
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:
require([
  "esri/tasks/RouteParameters", "esri/tasks/FeatureSet", "esri/SpatialReference",
  "esri/units", "dojo/_base/connect", ... 
], function(RouteParameters, FeatureSet, SpatialReference, Units, connect, ... ) {
  var routeParams = new RouteParameters();
  routeParams.stops = new FeatureSet();
  routeParams.returnRoutes = false;
  routeParams.returnDirections = true;
  routeParams.directionsLengthUnits = Units.MILES;
  routeParams.outSpatialReference = new SpatialReference({ wkid:102100 });
  
  connect.connect(routeTask, "onSolveComplete", showRoute);
  ...
});
Event Details
[ On Style Events | Connect Style Event ]

error

Fires when an error occurs when executing the task. Should be used in favor of onError. (Added at v3.5)
Event Object Properties:
<Error> error Error message returned in a JavaScript error object.

solve-complete

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;
  ...
}