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

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

Description

(Added at v1.4)
Input parameters for the RouteTask. Specify details such as: stop locations, barrier locations, the impedance attribute, etc.

Samples

Search for samples that use this class.

Constructors

NameSummary
new RouteParameters()Creates a new RouteParameters object.

Properties

NameTypeSummary
accumulateAttributesString[]The list of network attribute names to be accumulated with the analysis, i.e., which attributes should be returned as part of the response.
attributeParameterValuesObject[]Each element in the array is an object that describes the parameter values.
barriersObjectThe set of point barriers loaded as network locations during analysis.
directionsLanguageStringThe language used when computing directions.
directionsLengthUnitsStringThe length units to use when computing directions.
directionsOutputTypeStringDefines the amount of direction information returned.
directionsStyleNameStringThe style to be used when returning directions.
directionsTimeAttributeStringThe name of network attribute to use for the drive time when computing directions.
doNotLocateOnRestrictedElementsBooleanIf true, avoids network elements restricted by barriers or due to restrictions specified in restrictionAttributes.
findBestSequenceBooleanThe RouteTask can help you find the most efficient path for visiting a given list of stops.
ignoreInvalidLocationsBooleanIn routes where a stop is not located on a network or a stop could not be reached, the results will differ depending on the value of ignoreInvalidLocations.
impedanceAttributeStringThe network attribute name to be used as the impedance attribute in analysis.
outSpatialReferenceSpatialReferenceThe well-known ID of the spatial reference for the geometries returned with the analysis results.
outputGeometryPrecisionNumberThe precision of the output geometry after generalization.
outputGeometryPrecisionUnitsStringThe units of the output geometry precision.
outputLinesStringThe type of output lines to be generated in the result.
polygonBarriersObjectThe set of polygon barriers loaded as network locations during analysis.
polylineBarriersObjectThe set of polyline barriers loaded as network locations during analysis.
preserveFirstStopBooleanIf true, keeps the first stop fixed in the sequence even when findBestSequence is true.
preserveLastStopBooleanIf true, keeps the last stop fixed in the sequence even when findBestSequence is true.
restrictUTurnsStringSpecifies how U-Turns should be handled.
restrictionAttributesString[]The list of network attribute names to be used as restrictions with the analysis.
returnBarriersBooleanIf true, barriers are returned as the second parameter of RouteTask.onSolveComplete.
returnDirectionsBooleanIf true, directions are generated and returned in the directions property of each RouteResult.
returnPolygonBarriersBooleanIf true, polygon barriers are returned as the third parameter of RouteTask.onSolveComplete.
returnPolylineBarriersBooleanIf true, polyline barriers are returned as the fourth parameter of RouteTask.onSolveComplete.
returnRoutesBooleanIf true, routes are generated and returned in the route property of each RouteResult.
returnStopsBooleanIf true, stops are returned in the stops property of each RouteResult.
startTimeDateThe time the route begins.
startTimeIsUTCBooleanStart time is in UTC format.
stopsObjectThe set of stops loaded as network locations during analysis.
timeWindowsAreUTCBooleanIf true, the TimeWindowStart and TimeWindowEnd attributes of a stop are in UTC time (milliseconds).
travelModeObjectTravel modes define how a pedestrian, car, truck or other medium of transportation moves through the street network.
useHierarchyBooleanIf true, the hierarchy attribute for the network should be used in analysis.
useTimeWindowsBooleanA useful feature of the RouteTask is the ability to constrain stop visits to certain times of day, or "time windows".
Constructor Details

new RouteParameters()

Creates a new RouteParameters object.
Property Details

<String[]> accumulateAttributes

The list of network attribute names to be accumulated with the analysis, i.e., which attributes should be returned as part of the response. The default is as defined in the specific routing network layer used in your RouteTask. You can specify any attributes names listed in the Service Directory under "Network Dataset -> Network Attributes" as "Usage Type: esriNAUTCost". See also Understanding the network attribute.

<Object[]> attributeParameterValues

Each element in the array is an object that describes the parameter values. The object has the following properties: 
attributeName: The attribute name. String. 
parameterName: The parameter name. String. 
value: The parameter value. Number. 
Sample:
routeParams.attributeParameterValues = [
  {
    attributeName: "Time",
    parameterName: "25 MPH",
    value: "2.5"
  },
  {
    attributeName: "Time",
    parameterName: "35 MPH",
    value: "5.0"
  }
];

<Object> barriers

The set of point barriers loaded as network locations during analysis. Can be either an instance of DataLayer or FeatureSet.
At ArcGIS Server 10.1 an optional url property was added. Use this property to specify a REST query request to a Feature, Map or GP Service that returns a JSON feature set. The url property can be specified using DataFile Note that either the features or url property should be specified.
Sample:
require([
  "esri/tasks/RouteParameters", "esri/tasks/FeatureSet", "esri/graphic", 
  "esri/tasks/DataFile", ... 
], function(RouteParameters, FeatureSet, Graphic, DataFile, ... ) {
  var routeParams = new RouteParameters();

  //Add barriers as a FeatureSet
  routeParams.barriers = new FeatureSet();
  routeParams.barriers.features.push(
    map.graphics.add(
      new Graphic(
        evt.mapPoint,
        barrierSymbol
      )
    )
  );

  //Requires ArcGIS Server 10.1 or greater
  var networkServiceUrl = 'http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Network/USA/MapServer/'
  routeParams.barriers = new DataFile({
    url: networkServiceUrl + "/1/query?where=1%3D1&outFields=Name,RouteName&f=json"}
  );
  ...
});

<String> directionsLanguage

The language used when computing directions. The default is as defined in the specific routing network layer used in your RouteTask. By default, NAServer gets installed with en_US only - it is up to the server administrator to add additional languages.

<String> directionsLengthUnits

The length units to use when computing directions. The default is as defined in the specific routing network layer used in your RouteTask.
Known values: esriFeet | esriKilometers | esriMeters | esriMiles | esriNauticalMiles | esriYards

<String> directionsOutputType

Defines the amount of direction information returned. (Added at v3.3)
Known values: complete | complete-no-events | instructions-only | standard | summary-only
Default value: standard

<String> directionsStyleName

The style to be used when returning directions. The default will be as defined in the network layer. View the REST layer description for your network service to see a list of supported styles.  (Added at v3.3)

<String> directionsTimeAttribute

The name of network attribute to use for the drive time when computing directions. The default is as defined in the specific routing network layer used in your RouteTask.

<Boolean> doNotLocateOnRestrictedElements

If true, avoids network elements restricted by barriers or due to restrictions specified in restrictionAttributes.
Known values: true | false
Default value: false

<Boolean> findBestSequence

The RouteTask can help you find the most efficient path for visiting a given list of stops. This is sometimes known as the "traveling salesperson" problem. When the findBestSequence is set to true, the route solver is solving the Traveling Salesperson problem of computing the optimal sequence to visit the stops. As this is a combinatorial problem, we employ heuristics to solve this in a reasonable time. The heuristics do not guarantee the optimal sequence (as there is no good/fast way to prove optimality for large number of stops), it returns a solution that is close to optimal if not the optimal. The heuristic performs favorably when tested with known TSP benchmarks available in the OR research community.

If you want these stops to be visited in the most efficient way, specify the following parameters:

routeParams.findBestSequence=true;
routeParams.preserveFirstStop=false;
routeParams.preserveLastStop=false;
routeParams.returnStops = true;
Known values: true | false

<Boolean> ignoreInvalidLocations

In routes where a stop is not located on a network or a stop could not be reached, the results will differ depending on the value of ignoreInvalidLocations.

  • When false, the solve operation will fail if at least one of the stops specified cannot be located or reached.
  • When true, as long as there are at least two valid stops that have been connected by a route, a valid result is returned. If multiple routes are processed in a single request, as long as least one route is built, a valid result is returned. The list of routes that cannot be solved is included in the message parameter of RouteTask.onSolveComplete.
Known values: true | false

<String> impedanceAttribute

The network attribute name to be used as the impedance attribute in analysis. The default is as defined in the specific routing network layer used in your RouteTask. You can specify any attributes names listed in the Service Directory under "Network Dataset -> Network Attributes" as "Usage Type: esriNAUTCost". You can also specify a value of "none" to indicate that no network attributes should be used for impedance. If you specify an empty array, it will default to the default of the service.

For example, set impedanceAttribute="Time" for quickest route and impedanceAttribute="Length" for shortest drive, assuming the service has those two esriNAUTCost attributes.

For more information, see Understanding the network attribute.

<SpatialReference> outSpatialReference

The well-known ID of the spatial reference for the geometries returned with the analysis results. If not specified, the geometries are returned in the spatial reference of the map. See Projected Coordinate Systems and Geographic Coordinate Systems for the list of supported spatial references.

<Number> outputGeometryPrecision

The precision of the output geometry after generalization. If 0, no generalization of output geometry is performed. If present and positive, it represents the MaximumAllowableOffset parameter - generalization is performed according to IPolycurve.Generalize.

<String> outputGeometryPrecisionUnits

The units of the output geometry precision.
Known values: esriUnknownUnits | esriCentimeters | esriDecimalDegrees | esriDecimeters | esriFeet | esriInches | esriKilometers | esriMeters | esriMiles | esriMillimeters | esriNauticalMiles | esriPoints | esriYards
Default value: esriUnknownUnits

<String> outputLines

The type of output lines to be generated in the result. The default is as defined in the specific routing network layer used in your RouteTask. For possible values, see NAOutputLine.

<Object> polygonBarriers

The set of polygon barriers loaded as network locations during analysis. Can be either an instance of DataLayer or FeatureSet
At ArcGIS Server 10.1 an optional url property was added. Use this property to specify a REST query request to a Feature, Map or GP Service that returns a JSON feature set. The url property can be specified using DataFile Note that either the features or url property should be specified.
Sample:
require([
  "esri/map", "esri/tasks/RouteParameters", "esri/tasks/FeatureSet", "esri/symbols/SimpleFillSymbol",
  "esri/toolbars/Draw", "dojo/_base/connect", "esri/graphic", "esri/tasks/DataFile", ... 
], function(Map, FeatureSet, SimpleFillSymbol, Draw, connect, Graphic, DataFile, ... ) {
  var map = new Map( ... );
  var routeParams = new RouteParameters();
  routeParams.polygonBarriers = new FeatureSet();

  //Create a symbol for the barriers
  var polygonBarrierSymbol = new SimpleFillSymbol();

  //Use the draw toolbar to generate polygons to add as barriers.
  drawToolbar.activate(Draw.POLYGON);
  var drawEnd_connect = connect.connect(drawToolbar, "onDrawEnd", function(geometry) {
    routeParams.polygonBarriers.features.push(
    map.graphics.add(new Graphic(geometry, polygonBarrierSymbol))
  );

  //Requires ArcGIS Server 10.1 or greater
  var networkServiceUrl = 'http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Network/USA/MapServer/';
  routeParams.polygonBarriers = new DataFile({
    url: networkServiceUrl + "/7/query?where=1%3D1&outFields=Name,RouteName&f=json"}
  );
  ...
});

<Object> polylineBarriers

The set of polyline barriers loaded as network locations during analysis. Can be either an instance of DataLayer or FeatureSet

At ArcGIS Server 10.1 an optional url property was added. Use this property to specify a REST query request to a Feature, Map or GP Service that returns a JSON feature set. The url property can be specified using DataFile.  Note that either the features or url  property should be specified.
Sample:
require([
  "esri/map", "esri/tasks/RouteParameters", "esri/tasks/FeatureSet", "esri/symbols/SimpleFillSymbol",
  "esri/Color", "esri/toolbars/Draw", "dojo/_base/connect",
  "esri/graphic", "esri/tasks/DataFile", ... 
], function(Map, RouteParameters, FeatureSet, SimpleFillSymbol, Color, Draw, connect, Graphic, DataFile, ... ) {
  var map = new Map( ... );
  var routeParams = new RouteParameters();
  routeParams.polylineBarriers = new FeatureSet();

  //Create a symbol for the barriers
  var polylineBarrierSymbol = new SimpleLineSymbol().setColor(new Color([255,0,0]));

  //Use the draw toolbar to generate polylines to add as barriers.
  drawToolbar.activate(Draw.POLYLINE);
  var drawEnd_connect = connect.connect(drawToolbar, "onDrawEnd", function(geometry) {
    routeParams.polylineBarriers.features.push(
    map.graphics.add(new Graphic(geometry, polylineBarrierSymbol))
  );

  //Requires ArcGIS Server 10.1 or greater
  var networkServiceUrl = 'http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Network/USA/MapServer/';
  var lineBarriers = new DataFile({
    url: networkServiceUrl + "/6/query?where=1%3D1&outFields=Name,RouteName&f=json"}
  );
  ...
});

<Boolean> preserveFirstStop

If true, keeps the first stop fixed in the sequence even when findBestSequence is true. Only applicable if findBestSequence is true. The default is as defined in the specific routing network layer used in your RouteTask.
Known values: true | false

<Boolean> preserveLastStop

If true, keeps the last stop fixed in the sequence even when findBestSequence is true. Only applicable if findBestSequence is true. The default is as defined in the specific routing network layer used in your RouteTask.
Known values: true | false

<String> restrictUTurns

Specifies how U-Turns should be handled. The default is as defined in the specific routing network layer used in your RouteTask. See NAUTurn for a list of valid values.

<String[]> restrictionAttributes

The list of network attribute names to be used as restrictions with the analysis. The default is as defined in the specific routing network layer used in your RouteTask. Possible values are listed in the Service Directory under "Network Dataset -> Network Attributes". You can also specify a value of "none" to indicate that no network attributes should be used as restrictions. If you specify an empty array, it will default to the default of the service.

<Boolean> returnBarriers

If true, barriers are returned as the second parameter of RouteTask.onSolveComplete.
Known values: true | false
Default value: false

<Boolean> returnDirections

If true, directions are generated and returned in the directions property of each RouteResult.
Known values: true | false
Default value: false

<Boolean> returnPolygonBarriers

If true, polygon barriers are returned as the third parameter of RouteTask.onSolveComplete.
Known values: true | false

<Boolean> returnPolylineBarriers

If true, polyline barriers are returned as the fourth parameter of RouteTask.onSolveComplete.
Known values: true | false

<Boolean> returnRoutes

If true, routes are generated and returned in the route property of each RouteResult.
Known values: true | false
Default value: true

<Boolean> returnStops

If true, stops are returned in the stops property of each RouteResult.
Known values: true | false
Default value: false

<Date> startTime

The time the route begins. If not specified, the default is the time specified in the route service.

<Boolean> startTimeIsUTC

Start time is in UTC format (Added at v3.8)
Known values: true | false

<Object> stops

The set of stops loaded as network locations during analysis. Can be either an instance of DataLayer or FeatureSet. When RouteParameters.stops takes a FeatureSet, each feature in the FeatureSet must have a defined spatial reference. If the feature contains x and y attributes, those values are used for the stop, even if the feature includes geometry.

At ArcGIS Server 10.1 an optional url property was added. Use this property to specify a REST query request to a Feature, Map or GP Service that returns a JSON feature set. The url property can be specified using DataFile Note that either the features or url property should be specified.

Sample:
require([
  "esri/tasks/RouteParameters", "esri/tasks/FeatureSet", "esri/graphic", 
  "dojo/dom", "esri/tasks/DataFile", ... 
], function(RouteParameters, FeatureSet, Graphic, dom, DataFile, ... ) {
  var routeParams = new RouteParameters();

  //Add stops as a FeatureSet
  routeParams.stops = new FeatureSet();
  routeParams.stops.features.push(
    map.graphics.add(
      new Graphic(
        evt.mapPoint,
        stopSymbol,
        { RouteName: dom.byId("routeName").value }
      )
    )
  );

  //Requires ArcGIS Server 10.1 or greater
  var networkServiceUrl = 'http://sampleserver3.arcgisonline.com/ArcGIS/rest/services/Network/USA/MapServer/';
  routeParams.stops = new DataFile({
    url: networkServiceUrl + "/1/query?where=1%3D1&outFields=Name,RouteName&f=json"}
  );
  ...
});

<Boolean> timeWindowsAreUTC

If true, the TimeWindowStart and TimeWindowEnd attributes of a stop are in UTC time (milliseconds). If false, these two attribute values are in the time zone of the corresponding Stop. (Added at v3.17)
Default value: null

<Object> travelMode

Travel modes define how a pedestrian, car, truck or other medium of transportation moves through the street network. This can take values from the supportedTravelModes array returned by the RouteTask's getServiceDescription() method. Each Travel Mode is preset in the Network Analysis settings configured inside the network dataset, in a ArcGIS Online Organization, or inside a Portal for ArcGIS. (Added at v3.14)
Default value: Null
Object Specifications:
<travelMode>
<Object[]> attributeParameterValues Required An array of objects used to identify specific vehicle characteristics or how soft to make each restriction. Each object will have the following properties: attributeName, parameterName, and value. For additional information regarding attribute parameters, see the ArcGIS Online help topic.
<String> description Required A description of the travel mode used.
<String> distanceAttributeName Required The restriction attributes to respect during analysis. A list of possible restrictions of the ArcGIS Online services is listed here.

NOTE: Attribute names are specific to the network dataset. They may be different if using another Network Analysis service besides the one hosted via ArcGIS Online.
<String> id Required Unique identifier for the travel mode.
<String> impedanceAttributeName Required The cost attribute on which to optimize the analysis, for example "Miles", "Minutes", "Travel Time", "Kilometers", "TimeAt1KPH", "WalkTime", and "TruckTravelTime".

NOTE: Attribute names are specific to the network dataset. They may be different if using another Network Analysis service besides the one hosted via ArcGIS Online.
<String> name Required Name of the travel mode. Users of ArcGIS Online or Portal for ArcGIS can define custom Travel Modes inside their Organization settings. Authors of stand alone Network Analysis Services can define their own Travel Modes inside a network dataset.

Default ArcGIS Online Travel Modes are: "Driving Distance", "Rural Driving Distance", "Driving Time", "Rural Driving Time", "Trucking Distance", "Trucking Time", "Walking Distance", and "Walking Time".
<String[]> restrictionAttributeNames Required The restriction attributes to respect during analysis. A list of possible restrictions of the ArcGIS Online services is listed here.

NOTE: Attribute names are specific to the network dataset. They may be different if using another Network Analysis service besides the one hosted via ArcGIS Online.
<String> simplicationToleranceUnits Required Possible values are: "esriFeet", "esriKilometers", "esriMeters", "esriMiles", "esriNauticalMiles", and "esriYards".
<Number> simplificationTolerance Required How much to generalize the output geometry.
<String> timeAttributeName Required The time-based cost attribute for reporting directions,for example "Minutes", "Travel Time", "TimeAt1KPH", "WalkTime", and "TruckTravelTime".

NOTE: Attribute names are specific to the network dataset. They may be different if using another Network Analysis service besides the one hosted via ArcGIS Online.
<String> type Required The travel mode type. Possible values are: "AUTOMOBILE", "TRUCK", "WALK", or "OTHER".
<Boolean> useHierarchy Required Indicates whether or not to use a hierarchical road classification for faster analysis.
<String> uturnAtJunctions Required Specify where u-turns are allowed. Possible values are: "esriNFSBAllowBacktrack", "esriNFSBAtDeadEndsOnly", "esriNFSBNoBacktrack", and "esriNFSBAtDeadEndsAndIntersections".

<Boolean> useHierarchy

If true, the hierarchy attribute for the network should be used in analysis. The default is as defined in the specific routing network layer used in your RouteTask.
Known values: true | false

<Boolean> useTimeWindows

A useful feature of the RouteTask is the ability to constrain stop visits to certain times of day, or "time windows". If you were required to deliver orders to four homes and each customer was available during a limited time period during the day, the route task could help you find the most efficient path for making all the deliveries.

Time windows are treated as a "soft" constraint. This means that although the solver attempts to honor time windows, if necessary, it will violate the time windows of some stops in order to reach them. Remember also that the stops will be visited in the order they were added unless you set RouteParameters.findBestSequence to true.

Known values: true | false
Sample:

You set time windows as attributes on the stops. Here's an example of three stops with time windows:

routeParams.useTimeWindows = true;

var stop1 = new esri.Graphic(new esri.geometry.Point(-117.21,  34.065), stopSymbol);
stop1.attributes = new Object();
stop1.attributes.Name = "A";
stop1.attributes.TimeWindowStart = "8:00 AM";
stop1.attributes.TimeWindowEnd = "8:05 AM";

var stop2 = new esri.Graphic(new esri.geometry.Point(-117.185, 34.05 ), stopSymbol);
stop2.attributes = new Object();
stop2.attributes.Name = "B";
stop2.attributes.TimeWindowStart = "8:10 AM";
stop2.attributes.TimeWindowEnd = "8:15 AM";

var stop3 = new esri.Graphic(new esri.geometry.Point(-117.19,  34.062), stopSymbol);
stop3.attributes = new Object();
stop3.attributes.Name = "C";
stop3.attributes.TimeWindowStart = "8:20 AM";
stop3.attributes.TimeWindowEnd = "8:25 AM";