The Plan Routes task determines how to efficiently divide tasks among a mobile workforce.
You provide the input, which includes a set of stops and the number of vehicles available to visit the stops, and the tool assigns the stops to vehicles and returns routes showing how each vehicle can reach their assigned stops in the least amount of time.
With Plan Routes, mobile workforces reach more jobsites in less time, which increases productivity and improves customer service. Organizations often use Plan Routes to:
- Inspect homes, restaurants, and construction sites
- Provide repair, installation, and technical services
- Deliver items and small packages
- Make sales calls
- Provide van transportation from spectators' homes to events
The output from Plan Routes includes a layer of routes showing the shortest paths to visit the stops; a layer of the stops assigned to routes, as well as any stops that couldn't be reached due to the given parameter settings; and a layer of directions containing the travel itinerary for each route.
Licensing
As described in the Get Started topic, in order to use any analysis task, the administrator of the organization needs to grant you certain basic privileges. To use Plan Routes, you also need to be granted the Network Analysis privilege.
Limits
stops
—Maximum 2,000 features.Layer route
—Maximum 100.Count max
—Maximum 200.Stops Per Route -
point
—Maximum 250 features.Barrier Layer -
line
—An error will occur if the number of street features intersected by all the line barriers exceeds 500.Barrier Layer -
polygon
—An error will occur if the number of street features intersected by all the polygon barriers exceeds 2000.Barrier Layer - An error will occur if the tool takes more than four hours to execute. If this error occurs, try rerunning the analysis with fewer input features.
Request URL
http://<analysis url>/PlanRoutes/submitJob
Request Parameters
Parameter | Details | |||||||
---|---|---|---|---|---|---|---|---|
(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:
Examples:
| |||||||
(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 Example: | |||||||
(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 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 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.
Example: | |||||||
(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 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 The service automatically determines the time zones of the input starting locations ( Examples:
| |||||||
(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:
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:
Examples:
| |||||||
| Choose a field that uniquely identifies points in The See the the section of this topic entitled Starting and ending locations of routes to learn more. Example: | |||||||
| A The default value is Example: | |||||||
| Provide the locations where the people or vehicles end their routes. If 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:
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:
Examples:
| |||||||
| Choose a field that uniquely identifies points in The See the the section of this topic entitled Starting and ending locations of routes to learn more. Example: | |||||||
|
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 Use a JSON object representing travel mode settings for the For example, the following is a string representing the Walking Time travel mode as returned by the
Convert the value above to a valid JSON object and pass it as the value for the
| |||||||
| 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: | |||||||
| 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 ( The units are minutes. The default value, which is also the maximum value, is Example: | |||||||
|
When | |||||||
|
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:
Examples:
| |||||||
|
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:
Examples:
| |||||||
|
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:
Examples:
| |||||||
|
If provided, the task will create a feature service of the results. You define the name of the service. If an Syntax:
In ArcGIS Online or ArcGIS Enterprise 10.9.1 and later, you can overwrite an existing feature service by providing the Syntax:
or
| |||||||
| Context contains additional settings that affect task execution. For Plan Routes, there are two settings:
Syntax:
| |||||||
| The response format. The default response format is Values: |
Response
When you submit a request, the service assigns a unique job ID for the transaction. Syntax:
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}
After the initial request is submitted you can use the job
to periodically check the status of the job and messages as described in the topic Check job status. Once the job has successfully completed, you use the job
to retrive the results. To track the status, you can make a request of the following form:
http://<analysis url>/PlanRoutes/jobs/<jobId>
Accessing results
When the status of the job request is esri
, you can access the results of the analysis by making a request of the following form.
http://<analysis url>/PlanRoutes/jobs/<jobId>/results/<output parameter name>?token=<your token>&f=json
Parameter | Description |
---|---|
| The output routes that visit the assigned stops. Example:
The result has properties for parameter name, data type, and value. The contents of value depends upon the
See Feature Output for more information about how the result layer or collection is accessed. Fields in the output:
|
| The stops assigned to routes. Example:
Fields in the output:
|