Plan Routes

stopsLayer

(Required)

The points that the vehicles, drivers, or routes, should visit.

The fields on the input stops are included in the output stops, so if your input layer has a field such as Name, Address, or ProductDescription, that information will be available in the results.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

routeCount

(Required)

The maximum number of vehicles that are available to route. The tool supports up to 100 vehicles. The default value is 0.

The tool may be able to find and return a solution that uses fewer vehicles than the number you specify for this parameter. The number of vehicles returned also depends on four other parameters: the total number of stops in stopsLayer, the number of stops per vehicle you allow (maxStopsPerRoute), the travel time between stops, the time spent at each stop (stopServiceTime), and any limit you set on the total route time per vehicle (maxRouteTime).

Example:"routeCount": 8

maxStopsPerRoute

(Required)

The maximum number of stops a route, or vehicle, is allowed to visit. The largest value you can specify is 200. The default value is zero.

This is one of two parameters that balance the overall workload across routes. The other is maxRouteTime.

By lowering the maximum number of stops that can be assigned to each vehicle, the vehicles are more likely to have an equal number of stops assigned to them. This helps balance workloads among drivers. The drawback, however, is that it may result in a solution that is less efficient.

By increasing the stops per vehicle, the tool has more freedom to find more efficient solutions; however, the workload may be unevenly distributed among drivers and vehicles. Note that you can balance workloads by time instead of number of stops by specifying a value for the maxRouteTime parameter.

The following examples demonstrate the effects of limiting the maximum stops per vehicle or the total time per vehicle. In all of these examples, two routes start at the same location and visit a total of six stops.

	Balanced travel times and stops per route: The stops are more or less uniformly spread apart, so setting maxStopsPerRoute=3 to evenly distribute the workload results in routes that are roughly the same duration.
	Balanced stops per route but unbalanced travel times: Five of the six stops are clustered near the starting location, but one stop is set apart and requires a much longer drive to be reached. Dividing the stops equally between the two routes (maxStopsPerRoute=3) causes unbalanced travel times.
	Unbalanced stops per route but balanced travel times: The stops are in the same location as the previous graphic. By increasing the value of maxStopsPerRoute to 4, and limiting the total travel time per vehicle (maxRouteTime), the travel times are balanced even though one route visits more stops.

Example: "maxStopsPerRoute": 3

routeStartTime

(Required)

Specify when the vehicles or people start their routes. The time is specified as Unix time (milliseconds since midnight, January 1 1970).

The starting time value is the same for all routes; that is, all routes start at the same time.

Time zones affect what value you assign to routeStartTime. The time zone for the start time is based on the time zone in which the starting point is geographically located. For instance, if you have one route starting location and it is located in Pacific Standard Time (PST), the time you specify for routeStartTime is in PST.

There are a couple of scenarios to beware of given that starting times are based on where the starting points are located. One situation to be careful of is when you are located in one time zone but your starting locations are in another times zone. For instance, assume you are in Pacific Standard Time (UTC-8:00) and the vehicles you are routing are stationed in Mountain Standard Time (UTC-7:00). If it is currently 9:30 a.m. PST (10:30 a.m. MST) and your vehicles need to begin their routes in 30 minutes, you would set the start time to 11:00 a.m. That is, the starting locations for the routes are in the Mountain time zone, and it is currently 10:30 a.m. there, therefore, a starting time of 30 minutes from now is 11:00 a.m. Make sure you set the parameter according to the proper time zone.

The other situation that requires caution is where starting locations are spread across multiple time zones. The time you set for routeStartTime is specific to the time zone in which the starting location is—regardless of whether there are one or more starting locations in the problem you submit. For instance, if one route starts from a point in PST and another route starts from MST, and you enter 11:00 a.m. as the start time, the route in PST will start at 11:00 a.m. PST and the route in MST will start at 11:00 a.m. MST—a one-hour difference. The starting times are the same in local time, but offset in actual time, or UTC.

The service automatically determines the time zones of the input starting locations (startLayer) for you.

Examples:

• "timeOfDay": 1413964800000 // 8:00, 22 October 2014. Routes will depart their starting locations at 8:00 a.m., 22 October. Any routes with starting points in Mountain Standard Time start at 8:00 a.m., 22 October 2014 MST; any routes with starting points in Pacific Standard Time start at 8:00 a.m. 22 October 2014 PST, and so on.
• "timeOfDay": 1426674000000 // 10:20, 18 March 2015.

startLayer

(Required)

Provide the locations where the people or vehicles start their routes. You can specify one or many starting locations.

If specifying one, all routes will start from the one location. If specifying many starting locations, each route needs exactly one predefined starting location, and the following criteria must be met:

• The number of routes (routeCount) must equal the number of points in startLayer. (However, when only one point is included in startLayer, it is assumed that all routes start from the same location, and the two numbers can be different.)
• The starting location for each route must be identified with the startLayerRouteIDField parameter. This implies that the input points in startLayer have a unique identifier. Bear in mind that if you also have many ending locations, those locations need to be predetermined as well. The predetermined start and end locations of each route are paired together by matching route ID values.

See the section of this topic entitled Starting and ending locations of routes to learn more.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

startLayerRouteIDField

Choose a field that uniquely identifies points in startLayer. This parameter is required when startLayer has more than one point; it is ignored otherwise.

The startLayerRouteIDField parameter helps identify where routes begin and indicates the names of the output routes.

See the the section of this topic entitled Starting and ending locations of routes to learn more.

Example: "startLayerRouteIDField": "DriverName"

returnToStart

A true value indicates each route must end its trip at the same place where it started. The starting location is defined by the startLayer and startLayerRouteIDField parameters.

The default value is true.

Example: "returnToStart": "false"

endLayer

Provide the locations where the people or vehicles end their routes.

If endLayer is not specified, returnToStart must be set to true.

You can specify one or many ending locations.

If specifying one, all routes will end at the one location. If specifying many ending locations, each route needs exactly one predefined ending location, and the following criteria must be met:

• The number of routes (routeCount) must equal the number of points in endLayer. (However, when only one point is included in endLayer, it is assumed that all routes end at the same location, and the two numbers can be different.)
• The ending location for each route must be identified with the endLayerRouteIDField parameter. This implies that the input points in endLayer have a unique identifier. Bear in mind that if you also have many starting locations, those locations need to be predetermined as well. The predetermined start and end locations of each route are paired together by matching route ID values.

See the the section of this topic entitled Starting and ending locations of routes to learn more.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

endLayerRouteIDField

Choose a field that uniquely identifies points in endLayer. This parameter is required when endLayer has more than one point; it is ignored if there is one point or if returnToStart is true.

The endLayerRouteIDField parameter helps identify where routes end and indicates the names of the output routes.

See the the section of this topic entitled Starting and ending locations of routes to learn more.

Example: "endLayerRouteIDField": "Name"

travelMode

Specify the mode of transportation for the analysis.

Travel modes are managed in ArcGIS Online and can be configured by the administrator of your organization to better reflect your organization's workflows. You must specify the JSON object containing the settings for a travel mode supported by your organization. To get a list of supported travel modes, run the GetTravelModes operation from the Utilities service.

Use a JSON object representing travel mode settings for the travelMode parameter value. When you use the GetTravelModes operation from the Utilities service, the result is a string representing the travel mode JSON. You must convert this string to a valid JSON object using the API and pass the JSON object as the value for the travelMode parameter.

For example, the following is a string representing the Walking Time travel mode as returned by the GetTravelModes operation:

1
"{\"attributeParameterValues\": [{\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Walking\", \"value\": \"PROHIBITED\"}, {\"parameterName\": \"Restriction Usage\", \"attributeName\": \"Preferred for Pedestrians\", \"value\": \"PREFER_LOW\"}, {\"parameterName\": \"Walking Speed (km/h)\", \"attributeName\": \"WalkTime\", \"value\": 5}], \"description\": \"Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.\", \"impedanceAttributeName\": \"WalkTime\", \"simplificationToleranceUnits\": \"esriMeters\", \"uturnAtJunctions\": \"esriNFSBAllowBacktrack\", \"restrictionAttributeNames\": [\"Preferred for Pedestrians\", \"Walking\"], \"useHierarchy\": false, \"simplificationTolerance\": 2, \"timeAttributeName\": \"WalkTime\", \"distanceAttributeName\": \"Miles\", \"type\": \"WALK\", \"id\": \"caFAgoThrvUpkFBW\", \"name\": \"Walking Time\"}"

Convert the value above to a valid JSON object and pass it as the value for the travelMode parameter.

travelMode=

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "attributeParameterValues": [
    {
      "parameterName": "Restriction Usage",
      "attributeName": "Walking",
      "value": "PROHIBITED"
    },
    {
      "parameterName": "Restriction Usage",
      "attributeName": "Preferred for Pedestrians",
      "value": "PREFER_LOW"
    },
    {
      "parameterName": "Walking Speed (km\/h)",
      "attributeName": "WalkTime",
      "value": 5
    }
  ],
  "description": "Follows paths and roads that allow pedestrian traffic and finds solutions that optimize travel time. The walking speed is set to 5 kilometers per hour.",
  "impedanceAttributeName": "WalkTime",
  "simplificationToleranceUnits": "esriMeters",
  "uturnAtJunctions": "esriNFSBAllowBacktrack",
  "restrictionAttributeNames": [
    "Preferred for Pedestrians",
    "Walking"
  ],
  "useHierarchy": false,
  "simplificationTolerance": 2,
  "timeAttributeName": "WalkTime",
  "distanceAttributeName": "Miles",
  "type": "WALK",
  "id": "caFAgoThrvUpkFBW",
  "name": "Walking Time"
}

stopServiceTime

Indicates how much time, in minutes, is spent at each stop. The units are minutes. All stops are assinged the same service duration from this parameter—unique values for individual stops cannot be specified with this service.

Example: "stopServiceTime": 10 //The routes will spend 10 minutes at each visited stop.

maxRouteTime

The amount of time you specify here limits the maximum duration of each route. The maximum route time is an accumulation of travel time and the total service time at visited stops (stopServiceTime). This parameter is commonly used to prevent drivers from working too many hours or to balance workloads across routes or drivers.

The units are minutes. The default value, which is also the maximum value, is 525600 minutes, or one year.

Example: "maxRouteTime": 600 //None of the routes can last longer than 600 minutes, or 10 hours.

includeRouteLayers

When includeRouteLayers is set to true, each route from the result is also saved as a route layer item. A route layer includes all the information for a particular route, such as the stops assigned to the route as well as the travel directions. Creating route layers is useful if you want to share individual routes with other members in your organization. The route layers use the output feature service name provided in the outputName parameter as a prefix, and the route name generated as part of the analysis is added to create a unique name for each route layer.

pointBarrierLayer

Specify one or more point features that act as temporary restrictions (barriers) when traveling on the underlying streets.

A point barrier can model a fallen tree, an accident, a downed electrical line, or anything that completely blocks traffic at a specific position along the street. Travel is permitted on the street but not through the barrier.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

lineBarrierLayer

Specify one or more line features that prohibit travel anywhere the lines intersect the streets.

A line barrier prohibits travel anywhere the barrier intersects the streets. For example, a parade or protest that blocks traffic across several street segments can be modeled with a line barrier.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

polygonBarrierLayer

Specify one or more polygon features that completely restrict travel on the streets intersected by the polygons.

One use of this type of barrier is to model floods covering areas of the street network and making road travel there impossible.

Syntax: As described in detail in the Feature input topic, this parameter can be one of the following:

• A URL to a feature service layer with an optional filter to select specific features
• A feature collection

Examples:

• {"url": <feature service layer url>, "filter": <where clause>}
• {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}

outputName

If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection.

Syntax:

1
2
3
4
5
{
  "serviceProperties": {
    "name": "<service name>"
  }
}

In ArcGIS Online or ArcGIS Enterprise 10.9.1 and later, you can overwrite an existing feature service by providing the itemId value of the existing feature service and setting the overwrite property to true. Including the serviceProperties parameter is optional. As described in the Feature output topic, you must either be the owner of the feature service or have administrative privileges to perform the overwrite.

Syntax:

1
2
3
4
5
6
7
{

  "itemProperties": {
			"itemId": "<itemID of the existing feature service>",
			"overwrite": true
	}
}

or

1
2
3
4
5
6
7
8
9
{
"serviceProperties": {
    "name": "<existing service name>"
  },
"itemProperties": {
				"itemId": "<itemID of the existing feature service>",
				"overwrite": true
	}
}

context

Context contains additional settings that affect task execution. For Plan Routes, there are two settings:

1. Extent (extent)—A bounding box that defines the analysis area. Only those points in the inputLayer, startLayer, and endLayer that are within the bounding box can be visited by routes.
2. Output spatial reference (outSR)

• If the output is a feature service, the spatial reference will be the same as stopslayer. Setting outSR for feature services has no effect.
• If the output is a feature collection, the features will be in the spatial reference of the outSR value or the spatial reference of stopsLayer when outSR is not specified.

Syntax:

1
2
3
4
{
"extent" : {extent}
"outSR" : {spatial reference}
}

f

The response format. The default response format is html.

Values: html | json

routesLayer

The output routes that visit the assigned stops.

Example:

1
{"url":"http://<analysis url>/PlanRoutes/jobs/<jobId>/results/RoutesLayer"}

The result has properties for parameter name, data type, and value. The contents of value depends upon the outputName parameter provided in the initial request.

• If outputName was provided, value contains the url to the feature service layer.

1
2
3
4
5
{
"paramName":"routesLayer",
"dataType":"GPString",
"value":{"url":"<hosted featureservice layer url>"}
}

• If outputName was not provided, value contains a feature collection.

1
2
3
4
5
{
"paramName":"routesLayer",
"dataType":"GPString",
"value":{"layerDefinition": {}, "featureSet": {}  }
}

See Feature Output for more information about how the result layer or collection is accessed.

Fields in the output:

• RouteName—The name of the route. The name is automatically generated if one starting and one ending location is provided; the name is derived from the field value of startLayerRouteIDField or endLayerRouteIDField when many starting or ending locations are provided.
• StopCount—The total number of stops assigned to the route. The stop count excludes the two starting and ending points of a route.
• TotalTime—The expected duration of the route, in minutes. The total time includes the total service and travel times.
• TotalServiceTime—The total time, in minutes, expected to be spent servicing stops. The total service time excludes travel time. Note that route start and route end points don't have service times.
• TotalTravelTime—The total time, in minutes, expected to be spent traveling between stops. The total travel time excludes service times.
• TotalMiles—The total expected travel distance of the route, in miles.
• TotalKilometers—The total expected travel distance of the route, in kilometers.
• StartTime—The time and date the route is expected to begin its journey. The time is presented using the time zone in which the starting point is located.
• EndTime—The time and date the route is expected to end its journey. The time is presented using the time zone in which the ending point is located.
• StartTimeUTC—The time and date the route is expected to begin its journey. The time is presented using UTC.
• EndTimeUTC—The time and date the route is expected to end its journey. The time is presented using UTC.

assignedStopsLayer

The stops assigned to routes.

Example:

1
{"url":"http://<analysis url>/PlanRoutes/jobs/<jobId>/results/AssignedStopsLayer"}

Fields in the output:

• RouteName—The name of the route. The name is automatically generated if one starting and one ending location is provided; the name is derived from the field value of startLayerRouteIDField or endLayerRouteIDField when many starting or ending locations are provided.
• Sequence—The order in which the stop is visited by the route that is assigned to the stop.
• ServiceTime—The amount of time spent at the stop. The value is in minutes.
• FromPrevTravelTime—The expected travel time, in minutes, to reach the current stop from the previous stop. It is 0 for the first stop. The service times at stops are excluded from this value.
• FromPrevDistance—The expected travel distance, in miles, between the previous stop and the current stop. It is 0 for the first stop.
• FromPrevDistanceKilometers—The expected travel distance, in kilometers, between the previous stop and the current stop. It is 0 for the first stop.
• ArriveTime—The time and date the route is expected to arrive at the stop. The time is presented using the time zone in which the stop is located.
• DepartTime—The time and date the route is expected to depart the stop after any service time. The time is presented using the time zone in which the stop is located.
• ArriveTimeUTC—The time and date the route is expected to arrive at the stop. The time is presented using UTC.
• DepartTimeUTC—The time and date the route is expected to depart the stop. The time is presented using UTC.
• StopType—Indicates whether the stop represents the starting location of the route (Route start), the ending location of the route (Route end), or a typical stop along the route (Stop).

unassignedStopsLayer

The stops that couldn't be assigned to any routes.

Example:

1
{"url":"http://<analysis url>/PlanRoutes/jobs/<jobId>/results/UnassignedStopsLayer"}

Fields in the output:

• ViolatedConstraint—Indicates why the stop was not assigned to a route when the Status field has a value of Not Reached; it is blank otherwise.
• Status—Indicates whether the stop was located on a road segment (OK), not located (it was too far from a road segment), or not reached. When the value is Not Reached, the ViolatedConstraint field provides more information.