Plan Routes
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.
Note:
This task is designed to provide a simple solution to the most common uses of fleet routing, or assigning stops to routes, people, or vehicles and finding the best routes between the stops. If you require additional flexibility to solve a more specialized problem, consider using the Vehicle Routing Problem Service instead. It provides many more options, such as honoring time windows at stops; adding barriers to block portions of the road network; setting vehicle-specific limits on maximum travel time, maximum number of stops to visit, and so on.
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
- stopsLayer—maximum 2,000 features
- routeCount—maximum 100
- maxStopsPerRoute—maximum 200
- pointBarrierLayer—Maximum 250 features.
- lineBarrierLayer—An error will occur if the number of street features intersected by all the line barriers exceeds 500.
- polygonBarrierLayer—An error will occur if the number of street features intersected by all the polygon barriers exceeds 2000.
- An error will occur if the tool takes more than 4 hours to execute. If this error occurs, try rerunning the analysis with fewer input features.
Request URL
http://<analysis url>/PlanRoutes/submitJobRequest Parameters
| Parameter | Details | ||||||
|---|---|---|---|---|---|---|---|
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:
Examples:
| ||||||
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.
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:
| ||||||
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:
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:
| ||||||
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:
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:
| ||||||
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: Convert the value above to a valid JSON object and pass it as the value for the travelMode parameter. travelMode= Caution:Plan Routes task only supports time-based travel modes, i.e. travel modes that specify a time-based impedance attribute. A travel mode is time-based if the impedanceAttributeName property has the same value as the timeAttributeName property in the travel mode JSON. A distance based value for the travelMode parameter causes a failure. | ||||||
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. Caution:Route layers cannot be created when the output is a feature collection. The task will produce an error if an outputName value is not specified (which indicates feature collection output) and includeRouteLayers is set to true. | ||||||
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:
Examples:
| ||||||
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:
Examples:
| ||||||
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:
Examples:
| ||||||
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: Syntax: | ||||||
context |
Context contains additional settings that affect task execution. For Plan Routes, there are two settings:
Syntax: | ||||||
f | The response format. The default response format is html. Values: html | json |
Response
When you submit a request, the service assigns a unique job ID for the transaction.
{
"jobId": "<unique job identifier>",
"jobStatus": "<job status>"
}
After the initial
request is submitted you can use the
jobId to periodically check the status of the job and messages as described in the topic Checking job status.
Once the job has successfully completed, you use
the jobId 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 esriJobSucceded, 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 |
|---|---|
routesLayer | The output routes that visit the assigned stops. 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.
See Feature Output for more information about how the result layer or collection is accessed. Fields in the output:
|
assignedStopsLayer | The stops assigned to routes. Example: Fields in the output:
|
unassignedStopsLayer | The stops that couldn't be assigned to any routes. Example: Fields in the output:
|
Route names and starting and ending locations
Plan Routes determines how to assign stops to many routes. But before it can do that, it requires certain inputs that you provide, including the locations where each route starts and ends. This section describes how to set beginning and ending locations and how to associate them with specific routes, or drivers. It also describes how the output routes are automatically named given their starting or ending locations.
Several parameters can be used in combination to set the start and end points. To briefly introduce them, they are listed below with a short description of how they are relevant. These parameters are referenced in more detail in the subsections that follow.
- startLayer—This parameter is always required, but what is important to know when specifying the related parameters listed here is whether startlayer contains one or many points.
- startLayerRouteIDField—Required when more than one point is in startLayer.
- returnToStart—Set to true if you want routes to end where they began; set to false if they end elsewhere (you must also add the endLayer parameter when false).
- endLayer—Required when returnToStart is false; it is ignored otherwise.
- endLayerRouteIDField—Required when returnToStart is false and endLayer contains more than one point.
The illustrations in these subsections show two routes only for simplicity. The Plan Routes tool works in the same way when more routes are specified.
One starting point and returning to start
The most common and simplest problem to set up is one where all routes start and end at the same location. A charitable organization seeking to efficiently deliver donations to people in need parks its delivery vans at a single warehouse. On delivery days, volunteers load the vans, which then fan out to various stops to deliver the packages. The vans return to the warehouse when all the deliveries are made.
Provide the following parameters to set up this start-and-end problem type:
- startLayer—Include one point to represent the starting location (for example, the warehouse).
- returnToStart—Set to true.
The output routes start and end at the same, single location. 
It is assumed that any driver can be assigned to any route since all routes start and end at the same location; therefore, the routes are assigned generic names.
One starting point and one ending point
Sometimes all routes start at one location and end at another. For instance, when planning routes for several buses parked at a depot that will pick up spectators from their homes and take them to an event, such as a concert, the depot is specified as the single starting location, and the venue of the event becomes the single ending location.
Provide the following parameters to solve this problem type:
- startLayer—Include one point representing the starting location (for example, the bus depot).
- returnToStart—Set to false.
- endLayer—Include one point representing the ending location (for example, the concert).
The output routes start at one location and end at another.
Because all drivers start and end at the same two locations, respectively, it is assumed any driver can drive any route, and therefore the output routes are generically named.
Many starting points and returning to start
For this problem type, each route starts from a unique point, visits its assigned stops, and finishes at the place where it began. This problem type is used, for instance, to route inspectors who start the day at their homes, go to various inspection sites, and return home at the end of the day.
Provide the following parameters to solve this problem type:
- startLayer—Include multiple points in this layer: one for each starting location (for example, an inspector's home). Note that each route is always assigned its own starting point for this problem type. If a subset of routes start at the same location, add their starting points next to or on top of each other to ensure each route has its own corresponding starting location.
- startLayerRouteIDField—Choose the ID field for this parameter. The start layer must have a field that uniquely identifies the routes, or drivers. It can be a route number, the driver's name, or some other unique name.
- returnToStart—Set to true.
The output routes start at multiple locations and end at their starting locations.
The routes and their drivers start at unique locations, so startLayerRouteID is specified. The output route names are automatically generated to be the same as the route ID values so that the routes can be assigned and delivered to the appropriate drivers.
Many starting points and one ending point
Each route starts from a unique point, visits its assigned stops, and converges with the other routes at a single ending location for this problem type. For instance, school bus drivers in a rural school district park their buses at their country homes at night. In the morning, they start their routes from home, pick up students, and drop them off at one school.
Provide the following parameters to solve this problem type:
- startLayer—Include multiple points in this layer: one for each starting location (for example, the bus drivers' homes). Note that each route is always assigned its own starting point for this problem type. If a subset of routes start at the same location, add their starting points next to or on top of each other to ensure each route has its own corresponding starting location.
- startLayerRouteIDField—Choose the ID field for this parameter. The start layer must have a field that uniquely identifies the routes, or drivers. It can be a route number, the driver's name, or some other unique name.
- returnToStart—Set to false.
- endLayer—Include one point representing the ending location (for example, the school).
The output routes start at multiple locations and end at one location.
The routes and their drivers start at unique locations, so startLayerRouteID is specified. The output route names are automatically generated to be the same as the route ID values so that the routes can be assigned and delivered to the appropriate drivers.
One starting points to many ending points
In the one-to-many problem type, all routes start from one point, visit their assigned stops, and end at unique locations. For a utility company that needs to hang shut-off warning tags on the doors of delinquent customers, employees are offered extra pay to hang the tags on their way home from work. The employees who accept the task pick up the tags from the central office, drive to various stops to hang the tags, and end their routes at their own homes.
Provide the following parameters to solve this problem type:
- startLayer—Include one point representing the starting location (for example, the central office).
- returnToStart—Set to false.
- endLayer—Include multiple points in this layer: one for each ending location (for example, the employee homes). Note that each route is always assigned its own ending point for this problem type. If a subset of routes end at the same location, add their ending points next to or on top of each other to ensure each route has its own corresponding ending location.
- endLayerRouteIDField—Choose the ID field for this parameter. The end layer must have a field that uniquely identifies the routes, or drivers. It can be a route number, the driver's name, or some other unique name.
The output routes start at one location and end at multiple locations.
The routes and their drivers end at unique locations, so endLayerRouteID is specified. The output route names are automatically generated to be the same as the route ID values so that the routes can be assigned and delivered to the appropriate drivers.
Many starting points to many ending points
In some planning scenarios, each route has unique starting and ending locations.
Provide the following parameters to solve this problem type:
- startLayer—Include multiple points in this layer: one for each starting location. Note that each route is always assigned its own starting point for this problem type. If a subset of routes start at the same location, add their starting points next to or on top of each other to ensure each route has its own corresponding starting location.
- startLayerRouteIDField—Choose the ID field for this parameter. The start layer must have a field that uniquely identifies the routes, or drivers. It can be a route number, the driver's name, or some other unique name.
- returnToStart—Set to false.
- endLayer—Include multiple points in this layer: one for each ending location. Note that each route is always assigned its own ending point for this problem type. If a subset of routes end at the same location, add their ending points next to or on top of each other to ensure each route has its own corresponding ending location
- endLayerRouteIDField—Choose the ID field for this parameter. The end layer must have a field that uniquely identifies the routes, or drivers. It can be a route number, the driver's name, or some other unique name.
The output routes start at many locations and end at multiple locations.