Solve Vehicle Routing Problem (Network Analyst)

Summary

Creates a vehicle routing problem (VRP) network analysis layer, sets the analysis properties, and solves the analysis, which is ideal for setting up a VRP web service. A vehicle routing problem analysis layer finds the best routes for a fleet of vehicles.

Learn about the output from Solve Vehicle Routing Problem

Usage

  • The tool dialog box groups the various optional parameters into the following six categories to make it easier for you to manage them:

    • Advanced Analysis
    • Barriers
    • Custom Travel Mode
    • Network Locations
    • Output
    • Service Capabilities

Syntax

SolveVehicleRoutingProblem(orders, depots, routes, breaks, time_units, distance_units, network_dataset, output_workspace_location, output_unassigned_stops_name, output_stops_name, output_routes_name, output_directions_name, {default_date}, {uturn_policy}, {time_window_factor}, {spatially_cluster_routes}, {route_zones}, {route_renewals}, {order_pairs}, {excess_transit_factor}, {point_barriers}, {line_barriers}, {polygon_barriers}, {time_attribute}, {distance_attribute}, {use_hierarchy_in_analysis}, {restrictions}, {attribute_parameter_values}, {maximum_snap_tolerance}, {exclude_restricted_portions_of_the_network}, {feature_locator_where_clause}, {populate_route_lines}, {route_line_simplification_tolerance}, {populate_directions}, {directions_language}, {directions_style_name}, {save_output_layer}, {service_capabilities}, {ignore_invalid_order_locations}, {travel_mode}, {ignore_network_location_fields}, {time_zone_usage_for_time_fields}, {overrides}, {save_route_data})
ParameterExplanationData Type
orders

The orders that the routes of the VRP analysis should visit. An order can represent a delivery (for example, furniture delivery), a pickup (such as an airport shuttle bus picking up a passenger), or some type of service or inspection (a tree trimming job or building inspection, for instance).

The orders feature set has an associated attribute table. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

Shape:

The geometry field indicating the geographic location of the network analysis object.

Name:

The name of the order. The name must be unique. If the name is left null, a name is automatically generated at solve time.

ServiceTime:

This property specifies how much time will be spent at the network location when the route visits it; that is, it stores the impedance value for the network location. A zero or null value indicates the network location requires no service time.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

TimeWindowStart1:

The beginning time of the first time window for the network location. This field can contain a null value; a null value indicates no beginning time.

Note:
  • A time window only states when a vehicle can arrive at an order; it doesn't state when the service time must be completed. To account for service time and depart before the time window ends, subtract the ServiceTime field value from the TimeWindowEnd1 field value.

  • The time window fields can contain a time-only value or a date and time value in a date field and cannot be integers representing milliseconds since Epoch. The time zone for time window fields is specified using the time_zone_usage_for_time_fields parameter. If a time field such as TimeWindowStart1 has a time-only value (for example, 8:00 a.m.), the date is assumed to be the date specified by the Default Date property of the analysis layer. Using date and time values (for example, 7/11/2010 8:00 a.m.) allows you to set time windows that span multiple days.

  • The default date is ignored when any time window field includes a date with the time. To avoid an error in this situation, format all time windows in Depots, Routes, Orders, and Breaks to also include the date with the time.

  • If you're using traffic data, the time-of-day fields for the network location always reference the same time zone as the edge on which the network location is located.

TimeWindowEnd1:

The ending time of the first time window for the network location. This field can contain a null value; a null value indicates no ending time.

TimeWindowStart2:

The beginning time of the second time window for the network location. This field can contain a null value; a null value indicates that there is no second time window.

If the first time window is null as specified by the TimeWindowStart1 and TimeWindowEnd1 fields, the second time window must also be null.

If both time windows are nonnull, they can't overlap. Also, the second time window must occur after the first.

TimeWindowEnd2:

The ending time of the second time window for the network location. This field can contain a null value.

When TimeWindowStart2 and TimeWindowEnd2 are both null, there is no second time window.

When TimeWindowStart2 is not null but TimeWindowEnd2 is null, there is a second time window that has a starting time but no ending time. This is valid.

MaxViolationTime1:

A time window is considered violated if the arrival time occurs after the time window has ended. This field specifies the maximum allowable violation time for the first time window of the order. It can contain a zero value but can't contain negative values. A zero value indicates that a time window violation at the first time window of the order is unacceptable; that is, the first time window is hard. On the other hand, a null value indicates that there is no limit on the allowable violation time. A nonzero value specifies the maximum amount of lateness; for example, a route can arrive at an order up to 30 minutes beyond the end of its first time window.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

Time window violations can be tracked and weighted by the solver. Because of this, you can direct the VRP solver to take one of three approaches:

  • Minimize the overall violation time, regardless of the increase in travel cost for the fleet.
  • Find a solution that balances overall violation time and travel cost.
  • Ignore the overall violation time; instead, minimize the travel cost for the fleet.

By assigning an importance level for the Time Window Violation Importance parameter (time_window_factor in Python), you are essentially choosing one of these three approaches. In any case, the solver will return an error if the value set for MaxViolationTime1 is surpassed.

MaxViolationTime2:

The maximum allowable violation time for the second time window of the order. This field is analogous to the MaxViolationTime1 field.

InboundArriveTime:

Defines when the item to be delivered to the order will be ready at the starting depot.

The order can be assigned to a route only if the inbound arrive time precedes the route's latest start time value; this way, the route cannot leave the depot before the item is ready to be loaded onto it.

This field can help model scenarios involving inbound-wave transshipments. For example, a job at an order requires special materials that are not currently available at the depot. The materials are being shipped from another location and will arrive at the depot at 11:00 a.m. To ensure a route that leaves before the shipment arrives isn't assigned to the order, the order's inbound arrive time is set to 11:00 a.m. The special materials arrive at 11:00 a.m., they are loaded onto the vehicle, and the vehicle departs from the depot to visit its assigned orders.

Note:

  • The route's start time, which includes service times, must occur after the inbound arrive time. If a route begins before an order's inbound arrive time, the order cannot be assigned to the route. The assignment is invalid even if the route has a start-depot service time that lasts until after the inbound arrive time.

  • This time field can contain a time-only value or a date and time value. If a time-only value is set (for example, 11:00 AM), the date is assumed to be the date specified by the Default Date property of the analysis layer. The default date is ignored, however, when any time field in Depots, Routes, Orders, or Breaks includes a date with the time. In that case, specify all such fields with a date and time (for example, 7/11/2015 11:00 AM).

  • The VRP solver honors InboundArriveTime regardless of the DeliveryQuantities value.

  • If an outbound depart time is also specified, its time value must occur after the inbound arrive time.

  • The VRP Solver is not designed to solve problems more than one year in duration. Therefore, all service times and time windows must be less than a year.

OutboundDepartTime:

Defines when the item to be picked up at the order must arrive at the ending depot.

The order can be assigned to a route only if the route can visit the order and reach its end depot before the specified outbound depart time.

This field can help model scenarios involving outbound-wave transshipments. For instance, a shipping company sends out delivery trucks to pick up packages from orders and bring them into a depot where they are forwarded on to other facilities, en route to their final destination. At 3:00 p.m. every day, a semitrailer stops at the depot to pick up the high-priority packages and take them directly to a central processing station. To avoid delaying the high-priority packages until the next day's 3:00 p.m. trip, the shipping company tries to have delivery trucks pick up the high-priority packages from orders and bring them to the depot before the 3:00 p.m. deadline. This is done by setting the outbound depart time to 3:00 p.m.

Note:
  • The route's end time, including service times, must occur before the outbound depart time. If a route reaches a depot but doesn't complete its end-depot service time prior to the order's outbound depart time, the order cannot be assigned to the route.

  • This time field can contain a time-only value or a date and time value. If a time-only value is set (for example, 11:00 AM), the date is assumed to be the date specified by the Default Date property of the analysis layer. The default date is ignored, however, when any time field in Depots, Routes, Orders, or Breaks includes a date with the time. In that case, specify all such fields with a date and time (for example, 7/11/2015 11:00 AM).

  • The VRP solver honors OutboundDepartTime regardless of the PickupQuantities value.

  • If an inbound arrive time is also specified, its time value must occur before the outbound depart time.

DeliveryQuantities:

The size of the delivery. You can specify size in any dimension you want, such as weight, volume, or quantity. You can even specify multiple dimensions, for example, weight and volume.

Enter delivery quantities without indicating units. For example, if a 300-pound object needs to be delivered to an order, enter 300. You will need to remember that the value is in pounds.

If you are tracking multiple dimensions, separate the numeric values with a space. For instance, if you are recording the weight and volume of a delivery that weighs 2,000 pounds and has a volume of 100 cubic feet, enter 2000 100. Again, you need to remember the units—in this case, pounds and cubic feet. You also need to remember the sequence in which the values and their corresponding units are entered.

Make sure that Capacities for Routes and DeliveryQuantities and PickupQuantities for Orders are specified in the same manner; that is, the values need to be in the same units, and if you are using multiple dimensions, the dimensions need to be listed in the same sequence for all parameters. So if you specify weight in pounds, followed by volume in cubic feet for DeliveryQuantities, the capacity of your routes and the pickup quantities of your orders need to be specified the same way: weight in pounds and then volume in cubic feet. If you mix units or change the sequence, you will get unwanted results without receiving any warning messages.

An empty string or null value is equivalent to all dimensions being zero. If the string has an insufficient number of values in relation to the capacity count, or dimensions being tracked, the remaining values are treated as zeros. Delivery quantities can't be negative.

PickupQuantities:

The size of the pickup. You can specify size in any dimension you want, such as weight, volume, or quantity. You can even specify multiple dimensions, for example, weight and volume. You cannot, however, use negative values. This field is analogous to the DeliveryQuantities field of Orders.

Note:
In the case of an exchange visit, an order can have both delivery and pickup quantities.

Revenue:

The income generated if the order is included in a solution. This field can contain a null value—a null value indicates zero revenue—but it can't have a negative value.

Revenue is included in optimizing the objective function value but is not part of the solution's operating cost. That is, the TotalCost field in the route class never includes revenue in its output; however, revenue weights the relative importance of servicing orders.

SpecialtyNames:

A space-separated string containing the names of the specialties required by the order. A null value indicates that the order doesn't require specialties.

The spelling of any specialties listed in the Orders and Routes classes must match exactly so the VRP solver can link them together.

To illustrate what specialties are and how they work, assume a lawn care and tree trimming company has a portion of its orders that requires a bucket truck to trim tall trees. The company would enter BucketTruck in the SpecialtyNames field for these orders to indicate their special need. SpecialtyNames would be left as null for the other orders. Similarly, the company would also enter BucketTruck in the SpecialtyNames field of routes that are driven by trucks with hydraulic booms. It would leave the field null for the other routes. At solve time, the VRP solver assigns orders without special needs to any route, but it only assigns orders that need bucket trucks to routes that have them.

AssignmentRule:

This field specifies the rule for assigning the order to a route. It is constrained by a domain of values, which are listed below (their coded values are shown in parentheses).

  • Exclude (0)—The order is to be excluded from the subsequent solve operation.
  • Preserve route and relative sequence (1)—The solver must always assign the order to the preassigned route and at the preassigned relative sequence during the solve operation. If this assignment rule can't be followed, it results in an order violation.

    With this setting, only the relative sequence is maintained, not the absolute sequence. To illustrate what this means, imagine there are two orders: A and B. They have sequence values of 2 and 3, respectively. If you set their AssignmentRule field values to Preserve route and relative sequence, A's and B's actual sequence values may change after solving because other orders, breaks, and depot visits could still be sequenced before, between, or after A and B. However, B cannot be sequenced before A.

  • Preserve route (2)—The solver must always assign the order to the preassigned route during the solve operation. A valid sequence must also be set even though the sequence may or may not be preserved. If the order can't be assigned to the specified route, it results in an order violation.
  • Override (3)—The solver ignores the route and sequence preassignment (if any) for the order during the solve operation. It assigns a route and sequence to the order so as to minimize the overall value of the objective function. This is the default value.
  • Anchor first (4)—The solver ignores the route and sequence preassignment (if any) for the order during the solve operation. It assigns a route to the order, and makes it the first order on that route, so as to minimize the overall value of the objective function.
  • Anchor last (5)—The solver ignores the route and sequence preassignment (if any) for the order during the solve operation. It assigns a route to the order, and makes it the last order on that route, so as to minimize the overall value of the objective function.

This field can't contain a null value.

CurbApproach:

The CurbApproach property specifies the direction a vehicle may arrive at and depart from the network location. There are four choices (their coded values are shown in parentheses):

  • Either side of vehicle (0)—The vehicle can approach and depart the network location in either direction. U-turns are allowed. You should choose this setting if your vehicle can make a U-turn at the stop or if it can pull into a driveway or parking lot and turn around.
  • Right side of vehicle (1)—When the vehicle approaches and departs the network location, the curb must be on the right side of the vehicle. A U-turn is prohibited.
  • Left side of vehicle (2)—When the vehicle approaches and departs the network location, the curb must be on the left side of the vehicle. A U-turn is prohibited.
  • No U-Turn (3)—When the vehicle approaches the network location, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

RouteName:

The name of the route to which the order is assigned.

As an input field, this field is used to preassign an order to a specific route. It can contain a null value, indicating that the order is not preassigned to any route, and the solver determines the best possible route assignment for the order. If this is set to null, the sequence field must also be set to null.

After a solve operation, if the order is routed, the RouteName field contains the name of the route that the order is assigned to.

Sequence:

This indicates the sequence of the order on its assigned route.

As an input field, this field is used to specify the relative sequence for an order on the route. This field can contain a null value specifying that the order can be placed anywhere along the route. A null value can only occur together with a null RouteName value.

The input sequence values are non-negative and unique for each route (shared across depot visits, orders, and breaks), but do not need to start from 0 or be contiguous.

After a solve operation, the Sequence field contains the sequence value of the order on its assigned route. Output sequence values for a route are shared across depot visits, orders, and breaks; start from 1 (at the starting depot); and are consecutive. So the smallest possible output sequence value for a routed order is 2, since a route always begins at a depot.

Feature Set
depots

A depot is a location that a vehicle departs from at the beginning of the workday and returns to at the end of the workday. Vehicles are loaded (for deliveries) or unloaded (for pickups) at depots at the start of the route. In some cases, a depot can also act as a renewal location, whereby the vehicle can unload or reload and continue performing deliveries and pickups. A depot has open and close times, as specified by a hard time window. Vehicles can't arrive at a depot outside of this time window.

The depots feature set has an associated attribute table. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

Shape:

The geometry field indicating the geographic location of the network analysis object.

Name:

The name of the depot. The StartDepotName and EndDepotName fields of the routes record set reference the names you specify here. It is also referenced by the route renewals record set, when used.

Depot names are not case sensitive and must be nonempty and unique.

TimeWindowStart1:

The beginning time of the first time window for the network location. This field can contain a null value; a null value indicates no beginning time.

Note:
  • Time window fields can contain a time-only value or a date and time value. If a time field has a time-only value (for example, 8:00 a.m.), the date is assumed to be the date specified by the Default Date parameter of the analysis layer. Using date and time values (for example, 7/11/2010 8:00 a.m.) allows you to set time windows that span multiple days.

  • The default date is ignored when any time window field includes a date with the time. To avoid an error in this situation, format all time windows in Depots, Routes, Orders, and Breaks to also include the date with the time.

  • If you're using traffic data, the time-of-day fields for the network location always reference the same time zone as the edge on which the network location is located.

TimeWindowEnd1:

The ending time of the first time window for the network location. This field can contain a null value; a null value indicates no ending time.

TimeWindowStart2:

The beginning time of the second time window for the network location. This field can contain a null value; a null value indicates that there is no second time window.

If the first time window is null as specified by the TimeWindowStart1 and TimeWindowEnd1 fields, the second time window must also be null.

If both time windows are nonnull, they can't overlap. Also, the second time window must occur after the first.

TimeWindowEnd2:

The ending time of the second time window for the network location. This field can contain a null value.

When TimeWindowStart2 and TimeWindowEnd2 are both null, there is no second time window.

When TimeWindowStart2 is not null but TimeWindowEnd2 is null, there is a second time window that has a starting time but no ending time. This is valid.

CurbApproach:

The CurbApproach property specifies the direction a vehicle may arrive at and depart from the network location. There are four choices (their coded values are shown in parentheses):

  • Either side of vehicle (0)—The vehicle can approach and depart the network location in either direction. U-turns are allowed. You should choose this setting if your vehicle can make a U-turn at the stop or if it can pull into a driveway or parking lot and turn around.
  • Right side of vehicle (1)—When the vehicle approaches and departs the network location, the curb must be on the right side of the vehicle. A U-turn is prohibited.
  • Left side of vehicle (2)—When the vehicle approaches and departs the network location, the curb must be on the left side of the vehicle. A U-turn is prohibited.
  • No U-Turn (3)—When the vehicle approaches the network location, the curb can be on either side of the vehicle; however, the vehicle must depart without turning around.

Bearing:

The direction in which a point is moving. The units are degrees and are measured in a clockwise fashion from true north. This field is used in conjunction with the BearingTol field.

Bearing data is usually sent automatically from a mobile device that is equipped with a GPS receiver. Try to include bearing data if you are loading an order that is moving, such as a pedestrian or a vehicle.

Using this field tends to prevent adding locations to the wrong edges, which can occur when a vehicle is near an intersection or an overpass, for example. Bearing also helps Network Analyst determine which side of the street the point is on.

For more information, see Bearing and BearingTol.

BearingTol:

The bearing tolerance value creates a range of acceptable bearing values when locating moving points on an edge using the Bearing field. If the value from the Bearing field is within the range of acceptable values that are generated from the bearing tolerance on an edge, the point can be added as a network location there; otherwise, the closest point on the next-nearest edge is evaluated.

The units are in degrees, and the default value is 30. Values must be greater than zero and less than 180.

A value of 30 means that when Network Analyst attempts to add a network location on an edge, a range of acceptable bearing values is generated 15º to either side of the edge (left and right) and in both digitized directions of the edge.

For more information, see Bearing and BearingTol.

NavLatency:

This field is only used in the solve process if Bearing and BearingTol also have values; however, entering a NavLatency value is optional, even when values are present in Bearing and BearingTol. NavLatency indicates how much time is expected to elapse from the moment GPS information is sent from a moving vehicle to a server and the moment the processed route is received by the vehicle's navigation device. The time units of NavLatency are the same as the units of the cost attribute specified by the Time Attribute parameter.

Feature Set
routes

The routes that are available for the given vehicle routing problem. A route specifies vehicle and driver characteristics; after solving, it also represents the path between depots and orders.

A route can have start and end depot service times, a fixed or flexible starting time, time-based operating costs, distance-based operating costs, multiple capacities, various constraints on a driver's workday, and so on.

The routes record set has several attributes. The fields in the attribute table are listed and described below.

Name:

The name of the route. The name must be unique.

Network Analyst generates a unique name at solve time if the field value is null. Therefore, entering a value is optional in most cases. However, you must enter a name if your analysis includes breaks, route renewals, route zones, or orders that are preassigned to a route, because the route name is used as a foreign key in these cases. Note that route names are not case sensitive.

StartDepotName:

The name of the starting depot for the route. This field is a foreign key to the Name field in Depots.

If the StartDepotName value is null, the route will begin from the first order assigned. Omitting the start depot is useful when the vehicle's starting location is unknown or irrelevant to your problem. However, when StartDepotName is null, EndDepotName cannot also be null.

Virtual start depots are not allowed if orders or depots are in multiple time zones.

If the route is making deliveries and StartDepotName is null, it is assumed the cargo is loaded on the vehicle at a virtual depot before the route begins. For a route that has no renewal visits, its delivery orders (those with nonzero DeliveryQuantities values in the Orders class) are loaded at the start depot or virtual depot. For a route that has renewal visits, only the delivery orders before the first renewal visit are loaded at the start depot or virtual depot.

EndDepotName:

The name of the ending depot for the route. This field is a foreign key to the Name field in the Depots parameter.

StartDepotServiceTime:

The service time at the starting depot. This can be used to model the time spent for loading the vehicle. This field can contain a null value; a null value indicates zero service time.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

Note:

The service times at the start and end depots are fixed values (given by the StartDepotServiceTime and EndDepotServiceTime field values) and do not take into account the actual load for a route. For example, the time taken to load a vehicle at the starting depot may depend on the size of the orders. As such, the depot service times could be given values corresponding to a full truckload or an average truckload, or you could make your own time estimate.

EndDepotServiceTime:

The service time at the ending depot. This can be used to model the time spent for unloading the vehicle. This field can contain a null value; a null value indicates zero service time.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

Note:

The service times at the start and end depots are fixed values (given by the StartDepotServiceTime and EndDepotServiceTime field values) and do not take into account the actual load for a route. For example, the time taken to load a vehicle at the starting depot may depend on the size of the orders. As such, the depot service times could be given values corresponding to a full truckload or an average truckload, or you could make your own time estimate.

EarliestStartTime:

The earliest allowable starting time for the route. This is used by the solver in conjunction with the time window of the starting depot for determining feasible route start times.

This field can't contain null values and has a default time-only value of 8:00 a.m.; the default value is interpreted as 8:00 a.m. on the date given by the Default Date parameter (default_date in Python).

The default date is ignored when any time window field includes a date with the time. To avoid an error in this situation, format all time windows in Depots, Routes, Orders, and Breaks to also include the date with the time.

When using network datasets with traffic data across multiple time zones, the time zone for EarliestStartTime is the same as the time zone of the edge or junction on which the starting depot is located.

LatestStartTime:

The latest allowable starting time for the route. This field can't contain null values and has a default time-only value of 10:00 a.m; the default value is interpreted as 10:00 a.m. on the date given by the Default Date property of the analysis layer.

When using network datasets with traffic data across multiple time zones, the time zone for LatestStartTime is the same as the time zone of the edge or junction on which the starting depot is located.

ArriveDepartDelay

This field stores the amount of travel time needed to accelerate the vehicle to normal travel speeds, decelerate it to a stop, and move it off and on the network (for example, in and out of parking). By including an ArriveDepartDelay value, the VRP solver is deterred from sending many routes to service physically coincident orders.

The cost for this property is incurred between visits to noncoincident orders, depots, and route renewals. For example, when a route starts from a depot and visits the first order, the total arrive/depart delay is added to the travel time. The same is true when traveling from the first order to the second order. If the second and third orders are coincident, the ArriveDepartDelay value is not added between them since the vehicle doesn't need to move. If the route travels to a route renewal, the value is added to the travel time again.

Although a vehicle needs to slow down and stop for a break and accelerate afterward, the VRP solver cannot add the ArriveDepartDelay value for breaks. This means that if a route leaves an order, stops for a break, and continues to the next order, the arrive/depart delay is added only once, not twice.

To illustrate, assume there are five coincident orders in a high-rise building, and they are serviced by three different routes. This means three arrive/depart delays would be incurred; that is, three drivers would need to separately find parking places and enter the same building. However, if the orders could be serviced by just one route instead, only one driver would need to park and enter the building—only one arrive/depart delay would be incurred. Since the VRP solver tries to minimize cost, it will try to limit the arrive/depart delays and thus choose the single-route option. (Note that multiple routes may need to be sent when other constraints—such as specialties, time windows, or capacities—require it.)

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

Capacities:

The maximum capacity of the vehicle. You can specify capacity in any dimension, such as weight, volume, or quantity. You can even specify multiple dimensions, for example, weight and volume.

Enter capacities without indicating units. For example, assume your vehicle can carry a maximum of 40,000 pounds; you would enter 40000. You need to remember for future reference that the value is in pounds.

If you are tracking multiple dimensions, separate the numeric values with a space. For instance, if you are recording both weight and volume and your vehicle can carry a maximum weight of 40,000 pounds and a maximum volume of 2,000 cubic feet, Capacities should be entered as 40000 2000. Again, you need to remember the units. You also need to remember the sequence the values and their corresponding units are entered (pounds followed by cubic feet in this case).

Remembering the units and the unit sequence is important for a couple of reasons: one, so you can reinterpret the information later; two, so you can properly enter values for the DeliveryQuantities and PickupQuantities fields for Orders. To elaborate on the second point, note that the VRP solver simultaneously refers to Capacities, DeliveryQuantities, and PickupQuantities to make sure that a route doesn't become overloaded. Since units can't be entered in the field, Network Analyst can't make unit conversions, so you need to enter the values for the three fields using the same units and the same unit sequence to ensure that the values are correctly interpreted. If you combine units or change the sequence in any of the three fields, you will get unwanted results without receiving a warning messages. Thus, it is a good idea to set up a unit and unit-sequence standard beforehand and continually refer to it whenever entering values for these three fields.

An empty string or null value is equivalent to all values being zero. Capacity values can't be negative.

If the Capacities string has an insufficient number of values in relation to the DeliveryQuantities or PickupQuantities field for orders, the remaining values are treated as zero.

Caution:

The VRP solver only performs a simple Boolean test to determine whether capacities are exceeded. If a route's capacity value is greater than or equal to the total quantity being carried, the VRP solver will assume the cargo fits in the vehicle. This could be incorrect, depending on the actual shape of the cargo and the vehicle. For example, the VRP solver allows you to fit a 1,000-cubic-foot sphere into a 1,000-cubic-foot truck that is 8 feet wide. In reality, however, since the sphere is 12.6 feet in diameter, it won't fit in the 8-foot-wide truck.

FixedCost:

A fixed monetary cost that is incurred only if the route is used in a solution (that is, it has orders assigned to it). This field can contain null values; a null value indicates zero fixed cost. This cost is part of the total route operating cost.

CostPerUnitTime:

The monetary cost incurred—per unit of work time—for the total route duration, including travel times as well as service times and wait times at orders, depots, and breaks. This field can't contain a null value and has a default value of 1.0.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

CostPerUnitDistance:

The monetary cost incurred—per unit of distance traveled—for the route length (total travel distance). This field can contain null values; a null value indicates zero cost.

The unit for this field value is specified by the Distance Field Units parameter (distance_units for Python).

OvertimeStartTime:

The duration of regular work time before overtime computation begins. This field can contain null values; a null value indicates that overtime does not apply.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

For example, if the driver is to be paid overtime when the total route duration extends beyond eight hours, OvertimeStartTime is specified as 480 (8 hours * 60 minutes/hour), given the Time Field Units parameter is set to Minutes.

CostPerUnitOvertime:

The monetary cost incurred per time unit of overtime work. This field can contain null values; a null value indicates that the CostPerUnitOvertime value is the same as the CostPerUnitTime value.

MaxOrderCount:

The maximum allowable number of orders on the route. This field can't contain null values and has a default value of 30.

MaxTotalTime:

The maximum allowable route duration. The route duration includes travel times as well as service and wait times at orders, depots, and breaks. This field can contain null values; a null value indicates that there is no constraint on the route duration.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

MaxTotalTravelTime:

The maximum allowable travel time for the route. The travel time includes only the time spent driving on the network and does not include service or wait times.

This field can contain null values; a null value indicates there is no constraint on the maximum allowable travel time. This field value can't be larger than the MaxTotalTime field value.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

MaxTotalDistance:

The maximum allowable travel distance for the route.

The unit for this field value is specified by the Distance Field Units parameter (distance_units for Python).

This field can contain null values; a null value indicates that there is no constraint on the maximum allowable travel distance.

SpecialtyNames:

A space-separated string containing the names of the specialties supported by the route. A null value indicates that the route does not support any specialties.

This field is a foreign key to the SpecialtyNames field in the Orders parameter.

To illustrate what specialties are and how they work, assume a lawn care and tree trimming company has a portion of its orders that requires a bucket truck to trim tall trees. The company would enter BucketTruck in the SpecialtyNames field for these orders to indicate their special need. SpecialtyNames would be left as null for the other orders. Similarly, the company would also enter BucketTruck in the SpecialtyNames field of routes that are driven by trucks with hydraulic booms. It would leave the field null for the other routes. At solve time, the VRP solver assigns orders without special needs to any route, but it only assigns orders that need bucket trucks to routes that have them.

AssignmentRule:

This specifies whether or not the route can be used when solving the problem. This field is constrained by a domain of values, and the possible values are the following:

  • Include—The route is included in the solve operation. This is the default value.
  • Exclude—The route is excluded from the solve operation.

Record Set
breaks

The rest periods, or breaks, for the routes in a given vehicle routing problem. A break is associated with exactly one route, and it can be taken after completing an order, while en route to an order, or prior to servicing an order. It has a start time and a duration, for which the driver may or may not be paid. There are three options for establishing when a break begins: using a time window, a maximum travel time, or a maximum work time.

The breaks record set has associated attributes. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

RouteName:

The name of the route that the break applies to. Although a break is assigned to exactly one route, many breaks can be assigned to the same route.

This field is a foreign key to the Name field in the Routes class and can't have a null value.

Precedence:

Precedence values sequence the breaks of a given route. Breaks with a precedence value of 1 occur before those with a value of 2, and so on.

All breaks must have a precedence value, regardless of whether they are time-window, maximum-travel-time, or maximum-work-time breaks.

ServiceTime

The duration of the break. This field can't contain null values and has a default value of 60.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

TimeWindowStart:

The starting time of the break's time window. Half-open time windows are invalid for Breaks.

If this field has a value, MaxTravelTimeBetweenBreaks and MaxCumulWorkTime must be null; moreover, all other breaks in the analysis layer must have null values for MaxTravelTimeBetweenBreaks and MaxCumulWorkTime.

An error will occur at solve time if a route has multiple breaks with overlapping time windows.

The time window fields in breaks can contain a time-only value or a date and time value in a date field and cannot be integers representing milliseconds since Epoch. The time zone for time window fields is specified using the time_zone_usage_for_time_fields parameter. If a time field, such as TimeWindowStart, has a time-only value (for example, 12:00 p.m.), the date is assumed to be the date specified by the Default Date parameter (default_date in Python). Using date and time values (for example, 7/11/2012 12:00 p.m.) allows you to specify time windows that span two or more days. This is beneficial when a break should be taken sometime before and after midnight.

The default date is ignored when any time window field includes a date with the time. To avoid an error in this situation, format all time windows in Depots, Routes, Orders, and Breaks to also include the date with the time.

TimeWindowEnd:

The ending time of the break's time window. Half-open time windows are invalid for Breaks.

If this field has a value, MaxTravelTimeBetweenBreaks and MaxCumulWorkTime must be null; moreover, all other breaks in the analysis layer must have null values for MaxTravelTimeBetweenBreaks and MaxCumulWorkTime.

MaxViolationTime:

This field specifies the maximum allowable violation time for a time-window break. A time window is considered violated if the arrival time falls outside the time range.

A zero value indicates the time window cannot be violated; that is, the time window is hard. A nonzero value specifies the maximum amount of lateness; for example, the break can begin up to 30 minutes beyond the end of its time window, but the lateness is penalized pursuant to the Time Window Violation Importance parameter (time_window_factor in Python).

This property can be null; a null value with TimeWindowStart and TimeWindowEnd values indicates that there is no limit on the allowable violation time. If MaxTravelTimeBetweenBreaks or MaxCumulWorkTime has a value, MaxViolationTime must be null.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

MaxTravelTimeBetweenBreaks:

The maximum amount of travel time that can be accumulated before the break is taken. The travel time is accumulated either from the end of the previous break or, if a break has not yet been taken, from the start of the route.

If this is the route's final break, MaxTravelTimeBetweenBreaks also indicates the maximum travel time that can be accumulated from the final break to the end depot.

This field is designed to limit how long a person can drive until a break is required. For instance, if the Time Field Units parameter (time_units in Python) of the analysis is set to Minutes, and MaxTravelTimeBetweenBreaks has a value of 120, the driver will get a break after two hours of driving. To assign a second break after two more hours of driving, the second break's MaxTravelTimeBetweenBreaks field value should be 120.

If this field has a value, TimeWindowStart, TimeWindowEnd, MaxViolationTime, and MaxCumulWorkTime must be null for an analysis to solve successfully.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

MaxCumulWorkTime:

The maximum amount of work time that can be accumulated before the break is taken. Work time is always accumulated from the beginning of the route.

Work time is the sum of travel time and service times at orders, depots, and breaks. Note, however, that this excludes wait time, which is the time a route (or driver) spends waiting at an order or depot for a time window to begin.

This field is designed to limit how long a person can work until a break is required. For instance, if the Time Field Units parameter (time_units in Python) is set to Minutes, MaxCumulWorkTime has a value of 120, and ServiceTime has a value of 15, the driver will get a 15-minute break after two hours of work.

Continuing with the last example, assume a second break is needed after three more hours of work. To specify this break, you would enter 315 (five hours and 15 minutes) as the second break's MaxCumulWorkTime value. This number includes the MaxCumulWorkTime and ServiceTime values of the preceding break, along with the three additional hours of work time before granting the second break. To avoid taking maximum-work-time breaks prematurely, remember that they accumulate work time from the beginning of the route and that work time includes the service time at previously visited depots, orders, and breaks.

If this field has a value, TimeWindowStart, TimeWindowEnd, MaxViolationTime, and MaxTravelTimeBetweenBreaks must be null for an analysis to solve successfully.

The unit for this field value is specified by the Time Field Units parameter (time_units in Python).

IsPaid:

A Boolean value indicating whether the break is paid or unpaid. A True value indicates that the time spent at the break is included in the route cost computation and overtime determination. A False value indicates otherwise. The default value is True.

Sequence:

As an input field, this indicates the sequence of the break on its route. This field can contain null values. The input sequence values are positive and unique for each route (shared across renewal depot visits, orders, and breaks) but need not start from 1 or be contiguous.

The solver modifies the sequence field. After solving, this field contains the sequence value of the break on its route. Output sequence values for a route are shared across depot visits, orders, and breaks; start from 1 (at the starting depot); and are consecutive.

Record Set
time_units

Specifies the time units for all time-based field values in the analysis.

  • SecondsSeconds
  • MinutesMinutes
  • HoursHours
  • DaysDays

Many features and records in a VRP analysis have fields for storing time values, such as ServiceTime for orders and CostPerUnitTime for routes. To minimize data entry requirements, these field values don't include units. Instead, all distance-based field values must be entered in the same units, and this parameter is used to specify the units of those values.

Note that output time-based fields use the same units specified by this parameter.

This time unit doesn't need to match the time unit of the network Time Attribute parameter (time_attribute in Python).

String
distance_units

Specifies the distance units for all distance-based field values in the analysis.

  • MilesMiles
  • KilometersKilometers
  • FeetFeet
  • YardsYards
  • MetersMeters
  • NauticalMilesNautical miles

Many features and records in a VRP analysis have fields for storing distance values, such as MaxTotalDistance and CostPerUnitDistance for routes. To minimize data entry requirements, these field values don't include units. Instead, all distance-based field values must be entered in the same units, and this parameter is used to specify the units of those values.

Note that output distance-based fields use the same units specified by this parameter.

This distance unit doesn't need to match the distance unit of the network Distance Attribute (distance attribute in Python).

String
network_dataset

The network dataset on which the vehicle routing problem analysis will be performed. The network dataset must have a time-based cost attribute, since the VRP solver minimizes time.

Network Dataset Layer
output_workspace_location

The file geodatabase or in-memory workspace in which the output feature classes will be created. This workspace must already exist. The default output workspace is in memory.

Workspace
output_unassigned_stops_name

The name of the output feature class that will contain any unreachable depots or unassigned orders.

String
output_stops_name

The name of the feature class that will contain the stops visited by routes. This feature class includes stops at depots, orders, and breaks.

String
output_routes_name

The name of the feature class that will contain the routes of the analysis.

String
output_directions_name

The name of the feature class that will contain the directions for the routes.

String
default_date
(Optional)

The default date for time field values that specify a time of day without including a date.

Date
uturn_policy
(Optional)

Specifies the U-turn policy that will be used at junctions. Allowing U-turns implies that the solver can turn around at a junction and double back on the same street. Given that junctions represent street intersections and dead ends, different vehicles may be able to turn around at some junctions but not at others—it depends on whether the junction represents an intersection or a dead end. To accommodate this, the U-turn policy parameter is implicitly specified by the number of edges that connect to the junction, which is known as junction valency. The acceptable values for this parameter are listed below; each is followed by a description of its meaning in terms of junction valency.

  • ALLOW_UTURNSU-turns are permitted at junctions with any number of connected edges. This is the default value.
  • NO_UTURNSU-turns are prohibited at all junctions, regardless of junction valency. However, U-turns are still permitted at network locations even when this setting is chosen, but you can set the individual network location's CurbApproach property to prohibit U-turns there as well.
  • ALLOW_DEAD_ENDS_ONLYU-turns are prohibited at all junctions, except those that have only one adjacent edge (a dead end).
  • ALLOW_DEAD_ENDS_AND_INTERSECTIONS_ONLYU-turns are prohibited at junctions where exactly two adjacent edges meet but are permitted at intersections (junctions with three or more adjacent edges) and dead ends (junctions with exactly one adjacent edge). Often, networks have extraneous junctions in the middle of road segments. This option prevents vehicles from making U-turns at these locations.

If you need a more precisely defined U-turn policy, consider adding a global turn delay evaluator to a network cost attribute or adjusting its settings if one exists, and pay particular attention to the configuration of reverse turns. You can also set the CurbApproach property of your network locations.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

String
time_window_factor
(Optional)

Specifies the importance of honoring time windows. There are three options, which are listed and described below.

  • LowPlaces more importance on minimizing drive times and less on arriving at stops on time. You may want to use this setting if you have a growing backlog of service requests. For the purpose of servicing more orders in a day and reducing the backlog, you can choose this setting even though customers may be inconvenienced with your late arrivals.
  • MediumBalances the importance of minimizing drive times and arriving within time windows. This is the default value.
  • HighPlaces more importance on arriving at stops on time and less on minimizing drive times. Organizations that make time-critical deliveries or that are concerned with customer service would choose this setting.
String
spatially_cluster_routes
(Optional)

Specifies whether to use spatial clustering.

  • CLUSTER The orders assigned to an individual route will be spatially clustered. Clustering orders tends to keep routes in smaller areas and reduce how often route lines intersect one another; yet, clustering can increase overall travel times. This is the default.
  • NO_CLUSTERThe solver will not prioritize spatially clustering orders and the route lines may intersect. Use this option if route zones are specified.
Boolean
route_zones
(Optional)

Delineates work territories for given routes. A route zone is a polygon feature and is used to constrain routes to servicing only those orders that fall within or near the specified area. The following are examples of when route zones may be useful:

  • Some of your employees don't have the required permits to perform work in certain states or communities. You can create a hard route zone so they only visit orders in areas where they meet the requirements.
  • One of your vehicles breaks down frequently, so you want to minimize response time by having it only visit orders that are close to your maintenance garage. You can create a soft or hard route zone to keep the vehicle nearby.

The route zones feature set has an associated attribute table. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

Shape:

The geometry field indicating the geographic location of the network analysis object.

RouteName:

The name of the route to which this zone applies. A route zone can have a maximum of one associated route. This field can't contain null values, and it is a foreign key to the Name field in the Routes feature layer.

IsHardZone:

A Boolean value indicating a hard or soft route zone. A True value indicates that the route zone is hard; that is, an order that falls outside the route zone polygon can't be assigned to the route. The default value is True (1). A False value (0) indicates that such orders can still be assigned, but the cost of servicing the order is weighted by a function that is based on the Euclidean distance from the route zone. Basically, this means that as the straight-line distance from the soft zone to the order increases, the likelihood of the order being assigned to the route decreases.

Feature Set
route_renewals
(Optional)

Specifies the intermediate depots that routes can visit to reload or unload the cargo they are delivering or picking up. Specifically, a route renewal links a route to a depot. The relationship indicates that the route can renew (reload or unload while en route) at the associated depot.

Route renewals can be used to model scenarios in which a vehicle picks up a full load of deliveries at the starting depot, services the orders, returns to the depot to renew its load of deliveries, and continues servicing more orders. For example, in propane gas delivery, the vehicle may make several deliveries until its tank is nearly or completely depleted, visit a refueling point, and make more deliveries.

The following are rules and options to consider when also working with route seed points:

  • The reload/unload point, or renewal location, can be different from the start or end depot.
  • Each route can have one or many predetermined renewal locations.
  • A renewal location may be used more than once by a single route.
  • In some cases where there may be several potential renewal locations for a route, the closest available renewal location is chosen by the solver.

The route renewals record set has associated attributes. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

DepotName:

The name of the depot where this renewal takes place. This field can't contain a null value and is a foreign key to the Name field in the Depots feature layer.

RouteName:

The name of the route that this renewal applies to. This field can't contain a null value and is a foreign key to the Name field in the Routes feature layer.

ServiceTime:

The service time for the renewal. This field can contain a null value; a null value indicates zero service time.

The unit for this field value is specified by the Time Field Units property of the analysis layer.

Note:

The time taken to load a vehicle at a renewal depot may depend on the size of the vehicle and how full or empty the vehicle is. However, the service time for a route renewal is a fixed value and does not take into account the actual load. As such, the renewal service time should be given a value corresponding to a full truckload, an average truckload, or another time estimate of your choice.

Record Set
order_pairs
(Optional)

Pairs pick up and deliver orders so they are serviced by the same route.

Sometimes it is required that the pick up and delivery of orders be paired. For example, a courier company may need to have a route pick up a high-priority package from one order and deliver it to another without returning to a depot, or sorting station, to minimize delivery time. These related orders can be assigned to the same route with the appropriate sequence using order pairs. Moreover, restrictions on how long the package can stay in the vehicle can also be assigned; for example, the package might be a blood sample that has to be transported from the doctor's office to the lab within two hours.

The order pairs record set has associated attributes. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

FirstOrderName:

The name of the first order of the pair. This field is a foreign key to the Name field in the Orders feature layer.

SecondOrderName:

The name of the second order of the pair. This field is a foreign key to the Name field in the Orders feature layer.

The first order in the pair must be a pickup order; that is, the value for its DeliveryQuantities field is null. The second order in the pair must be a delivery order; that is, the value for its PickupQuantities field is null. The quantity that is picked up at the first order must agree with the quantity that is delivered at the second order. As a special case, both orders may have zero quantities for scenarios where capacities are not used.

Note:

The order quantities are not loaded or unloaded at depots.

MaxTransitTime:

The maximum transit time for the pair. The transit time is the duration from the departure time of the first order to the arrival time at the second order. This constraint limits the time-on-vehicle, or ride time, between the two orders. When a vehicle is carrying people or perishable goods, the ride time is typically shorter than that of a vehicle carrying packages or nonperishable goods. This field can contain null values; a null value indicates that there is no constraint on the ride time.

The unit for this field value is specified by the Time Field Units property of the analysis layer.

Excess transit time (measured with respect to the direct travel time between order pairs) can be tracked and weighted by the solver. Because of this, you can direct the VRP solver to take one of three approaches: minimize the overall excess transit time, regardless of the increase in travel cost for the fleet; find a solution that balances overall violation time and travel cost; or ignore the overall excess transit time and, instead, minimize the travel cost for the fleet. By assigning an importance level for the Excess Transit Time Importance parameter (excess_transit_factor in Python), you are in effect choosing one of these three approaches. Regardless of the importance level, the solver will always return an error if the MaxTransitTime value is surpassed.

Record Set
excess_transit_factor
(Optional)

Specifies the importance of reducing excess transit time of order pairs. Excess transit time is the amount of time exceeding the time required to travel directly between the paired orders. Excess time can be caused by driver breaks or travel to intermediate orders and depots.

  • LowPlaces more importance on minimizing overall solution cost and less on excess transit time. This setting is commonly used by courier services. Since couriers transport packages as opposed to people, they don't need to worry about ride time. Using this setting allows the couriers to service paired orders in the proper sequence and minimize the overall solution cost.
  • MediumBalances the importance of reducing excess transit time and reducing the overall solution cost. This is the default value.
  • HighPlaces more importance on the shortest transit time between paired orders and less on the overall travel costs. It makes sense to use this setting if you are transporting people between paired orders and you want to shorten their ride time. This is characteristic of taxi services.
String
point_barriers
(Optional)

Specifies point barriers, which are split into two types: restriction and added cost point barriers. They temporarily restrict traversal across or add impedance to points on the network. The point barriers are defined by a feature set, and the attribute values you specify for the point features determine whether they are restriction or added cost barriers. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

Shape:

The geometry field indicating the geographic location of the network analysis object.

Name:

The name of the barrier.

BarrierType:

Specifies whether the barrier restricts travel completely or adds cost when traveling through it. There are two options:

  • Restriction (0)—Prohibits traversing through the barrier. This is the default value.
  • Added Cost (2)—Traversing through the barrier increases the network cost by the amount specified in the Additional_Time and Additional_Distance fields.

Additional_Time:

If BarrierType is set to added cost, the value of the Additional_Time field indicates how much time is added to a route when the route passes through the barrier.

The unit for this field value is specified by the Time Field Units property of the analysis layer.

Additional_Distance:

If BarrierType is set to added cost, the value of the Additional_Distance field indicates how much impedance is added to a route when the route passes through the barrier.

The unit for this field value is specified by the Distance Field Units parameter.

Feature Set
line_barriers
(Optional)

Specifies line barriers, which temporarily restrict traversal across them. The line barriers are defined by a feature set. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

Shape:

The geometry field indicating the geographic location of the network analysis object.

Name:

The name of the barrier.

Feature Set
polygon_barriers
(Optional)

Specifies polygon barriers, which are split into two types: restriction and scaled cost polygon barriers. They temporarily restrict traversal or scale impedance on the parts of the network they cover. The polygon barriers are defined by a feature set, and the attribute values you specify for the polygon features determine whether they are restriction or scaled cost barriers. The fields in the attribute table are listed and described below.

ObjectID:

The system-managed ID field.

Shape:

The geometry field indicating the geographic location of the network analysis object.

Name:

The name of the barrier.

BarrierType:

Specifies whether the barrier restricts travel completely or scales the cost of traveling through it. There are two options:

  • Restriction (0)—Prohibits traversing through any part of the barrier. This is the default value.
  • Scaled Cost (1)—Scales the impedance of underlying edges by multiplying them by the value of the Attr_[Impedance] property. If edges are partially covered by the barrier, the impedance is apportioned and multiplied.

Scaled_Time:

The time-based impedance values of the edges underlying the barrier are multiplied by the value set in this field. This field is only relevant when the barrier is a scaled cost barrier.

Scaled_Distance:

The distance-based impedance values of the edges underlying the barrier are multiplied by the value set in this field. This field is only relevant when the barrier is a scaled cost barrier.

Feature Set
time_attribute
(Optional)

The network cost attribute to use when determining the travel time of network elements.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

String
distance_attribute
(Optional)

The network cost attribute to use when determining the distance of network elements.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

String
use_hierarchy_in_analysis
(Optional)
  • USE_HIERARCHYThe hierarchy attribute will be used for the analysis. Using a hierarchy results in the solver preferring higher-order edges to lower-order edges. Hierarchical solves are faster, and they can be used to simulate the preference of a driver who chooses to travel on freeways rather than local roads when possible—even if that means a longer trip. This option is valid only if the input network dataset has a hierarchy attribute.
  • NO_HIERARCHYThe hierarchy attribute will not be used for the analysis. If hierarchy is not used, the result is an exact route for the network dataset.

The parameter is not used if a hierarchy attribute is not defined on the network dataset used to perform the analysis.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

Boolean
restrictions
[restriction,...]
(Optional)

Indicates which network restriction attributes are respected during solve time.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

String
attribute_parameter_values
(Optional)

Specifies the parameter values for network attributes that have parameters. The record set has two columns that work together to uniquely identify parameters and another column that specifies the parameter value.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

The attribute parameter values record set has associated attributes. The fields in the attribute table are listed below and described.

ObjectID:

The system-managed ID field.

AttributeName:

The name of the network attribute whose attribute parameter is set by the table row.

ParameterName:

The name of the attribute parameter whose value is set by the table row. (Object type parameters cannot be updated using this tool.)

ParameterValue:

The value you want for the attribute parameter. If a value is not specified, the attribute parameter is set to null.

Record Set
maximum_snap_tolerance
(Optional)

The maximum snap tolerance is the furthest distance that Network Analyst searches when locating or relocating a point onto the network. The search looks for suitable edges or junctions and snaps the point to the nearest one. If a suitable location isn't found within the maximum snap tolerance, the object is marked as unlocated.

Linear Unit
exclude_restricted_portions_of_the_network
(Optional)

Specifies where network locations are placed.

  • EXCLUDEThe network locations are only placed on traversable portions of the network. This prevents placing network locations on elements that you can't reach due to restrictions or barriers. Before adding your network locations using this option, make sure that you have already added all the restriction barriers to the input network analysis layer to get expected results. This option is not applicable when adding barrier objects. In such cases, use "#" as the parameter value.
  • INCLUDEThe network locations are placed on all the elements of the network. The network locations that are added with this option may be unreachable during the solve process if they are placed on restricted elements.
Boolean
feature_locator_where_clause
[[dataset_name, SQL_Query],...]
(Optional)

An SQL expression used to select a subset of source features that limits on which network elements orders and depots can be located. For example, to ensure orders and depots are not located on limited-access highways, write an SQL expression that excludes those source features. Note that the other network analysis objects, such as barriers, ignore the feature locator WHERE clause when loading.

Value Table
populate_route_lines
(Optional)

Specifies whether lines that show the true shape of the routes will be generated.

  • NO_ROUTE_LINESNo shape will be generated for the output routes. You cannot generate driving directions if route lines aren't created.
  • ROUTE_LINESThe output routes will have the exact shape of the underlying network sources.
Boolean
route_line_simplification_tolerance
(Optional)

The simplification distance of the route geometry.

Simplification maintains critical points on a route, such as turns at intersections, to define the essential shape of the route and removes other points. The simplification distance you specify is the maximum allowable offset that the simplified line can deviate from the original line. Simplifying a line reduces the number of vertices and tends to reduce drawing times.

The value of this parameter is overridden when Travel Mode (travel_mode in Python) is set to any value other than custom.

Linear Unit
populate_directions
(Optional)

Specifies whether driving directions will be generated.

  • DIRECTIONSDriving directions will be generated. The feature class specified in the output_directions_name parameter is populated with turn-by-turn instructions for each route. The network dataset must support driving directions; otherwise, an error will occur when solving with directions.
  • NO_DIRECTIONSDirections will not be generated.
Boolean
directions_language
(Optional)

The language in which driving directions will be generated. The languages available in the drop-down list depend on which ArcGIS language packs are installed on your computer.

If you are going to publish this tool as part of a service on a separate server, the ArcGIS language pack that corresponds to the language you choose must be installed on that server for the tool to function properly. Also, if a language pack isn't installed on your computer, the language won't appear in the drop-down list; however, you can type a language code instead.

String
directions_style_name
(Optional)

Specifies the formatting style of directions.

  • NA DesktopPrintable turn-by-turn directions
  • NA NavigationTurn-by-turn directions designed for an in-vehicle navigation device
  • NA CampusTurn-by-turn walking directions designed for pedestrian routes
String
save_output_layer
(Optional)

Specifies whether the output includes a network analysis layer of the results.

  • NO_SAVE_OUTPUT_LAYERThe output will not include a network analysis layer of the results.
  • SAVE_OUTPUT_LAYERThe output will include a network analysis layer of the results.

In either case, stand-alone tables and feature classes are returned. However, a server administrator may want to choose to output a network analysis layer so the setup and results of the tool can be debugged using the Network Analyst controls in the ArcGIS Desktop environment. This can make the debugging process easier.

In ArcGIS Desktop, the default output location for the network analysis layer is in the scratch workspace, at the same level as the scratch geodatabase; that is, it is stored as a sibling of the scratch geodatabase. The output network analysis layer is stored as an .lyr file whose name starts with _ags_gpna and is followed by an alphanumeric GUID.

Boolean
service_capabilities
[[String, {Long}],...]
(Optional)

Specifies the maximum amount of computer processing that occurs when running this tool as a geoprocessing service. You may want to do this for one of two reasons: to avoid letting your server solve problems that require more resources or processing time than you want to allow, or to create multiple services with different VRP capabilities to support a business model. For example, if you have a tiered-service business model, you may want to provide a free VRP service that supports a maximum of five routes per solve and another service that is fee-based and supports more than five routes per solve.

In addition to limiting the maximum number of routes, you can limit the number of orders or point barriers that can be added to the analysis. Another way to control problem sizes is by setting a maximum number of features—usually street features—that line or polygon barriers can intersect. The last method is to force a hierarchical solve, even if the user chooses not to use a hierarchy, when orders are geographically dispersed beyond a given straight-line distance.

  • MAXIMUM POINT BARRIERSThe maximum number of point barriers allowed. An error is returned if this limit is exceeded. A null value indicates there is no limit.
  • MAXIMUM FEATURES INTERSECTING LINE BARRIERSThe maximum number of source features that can be intersected by all line barriers in the analysis. An error is returned if this limit is exceeded. A null value indicates there is no limit.
  • MAXIMUM FEATURES INTERSECTING POLYGON BARRIERSThe maximum number of source features that can be intersected by all polygon barriers in the analysis. An error is returned if this limit is exceeded. A null value indicates there is no limit.
  • MAXIMUM ORDERSThe maximum number of orders allowed in the analysis. An error is returned if this limit is exceeded. A null value indicates there is no limit.
  • MAXIMUM ROUTESThe maximum number of routes allowed in the analysis. An error is returned if this limit is exceeded. A null value indicates there is no limit.
  • FORCE HIERARCHY BEYOND DISTANCEThe maximum straight-line distance between orders before the vehicle routing problem is solved using the network's hierarchy. The units for this value are the same as those specified in the Distance Field Units parameter.If the network doesn't have a hierarchy attribute, this constraint is ignored. If Use Hierarchy in Analysis is checked, hierarchy is always used. If the Use Hierarchy in Analysis parameter is unchecked and this constraint has a null value, hierarchy is not forced.
  • MAXIMUM ORDERS PER ROUTEThe maximum number of orders that can be assigned to each route. An error is returned if this limit is exceeded. A null value indicates there is no limit.
Value Table
ignore_invalid_order_locations
(Optional)

Specifies whether invalid orders will be ignored when solving the vehicle routing problem.

  • HALT The solve operation will fail when any invalid orders are encountered. An invalid order is an order that the VRP solver can't reach. An order may be unreachable for a variety of reasons, including if it's located on a prohibited network element, it isn't located on the network at all, or it's located on a disconnected portion of the network. This is the default value equivalent to boolean false.
  • SKIP The solve operation will ignore any invalid orders and return a solution, given it didn't encounter any other errors.If you need to generate routes and deliver them to drivers immediately, you may be able to ignore invalid orders, solve, and distribute the routes to your drivers. Next, resolve any invalid orders from the last solve and include them in the VRP analysis for the next workday or work shift. This value is equivalent to Boolean true.
Boolean
travel_mode
(Optional)

Choose the mode of transportation for the analysis. CUSTOM is always a choice. For other travel mode names to appear, they must be present in the network dataset specified in the Network_Dataset parameter. (The arcpy.na.GetTravelModes function provides a dictionary of the travel mode objects configured on a network dataset, and the name property returns the name of a travel mode object.)

A travel mode is defined on a network dataset and provides override values for parameters that, together, model car, truck, pedestrian, or other modes of travel. By choosing a travel mode here, you don't need to provide values for the following parameters, which are overridden by values specified in the network dataset:

  • uturn_policy
  • time_attribute
  • distance_attribute
  • use_hierarchy_in_analysis
  • restrictions
  • attribute_parameter_values
  • route_line_simplification_tolerance

  • CUSTOMDefine a travel mode that fits your specific needs. When CUSTOM is chosen, the tool does not override the travel mode parameters listed above. This is the default value.
String
ignore_network_location_fields
(Optional)

Specifies whether the network location fields will be considered when locating orders, depots, or barriers on the network.

  • IGNORENetwork location fields will not be considered when locating the inputs on the network. Instead, the inputs will always be located by performing a spatial search.
  • HONORNetwork location fields will be considered when locating the inputs on the network. This is the default value.
Boolean
time_zone_usage_for_time_fields
(Optional)

Specifies the time zone for the following input date-time fields supported by the tool: TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, TimeWindowEnd2, InboundArriveTime, and OutboundDepartTime for orders; TimeWindowStart1, TimeWindowEnd1, TimeWindowStart2, and TimeWindowEnd2 for depots; EarliestStartTime and LatestStartTime for routes; and TimeWindowStart and TimeWindowEnd for breaks.

  • GEO_LOCAL The date-time values associated with the orders or depots are in the time zone in which the orders and depots are located. For routes, the date-time values are based on the time zone in which the starting depot for the route is located. If a route does not have a starting depot, all orders and depots across all the routes must be in a single time zone. For breaks, the date-time values are based on the time zone of the routes. For example, if your depot is located in an area that follows eastern standard time and has the first time window values (specified as TimeWindowStart1 and TimeWindowEnd1) of 8 a.m. and 5 p.m., respectively, the time window values will be treated as 8 a.m. and 5 p.m. eastern standard time.
  • UTC The date-time values associated with the orders or depots are in Coordinated Universal Time (UTC) and are not based on the time zone in which the orders or depots are located. For example, if your depot is located in an area that follows eastern standard time and has the first time window values (specified as TimeWindowStart1 and TimeWindowEnd1) of 8 a.m. and 5 p.m., respectively, the time window values will be treated as 12 p.m. and 9 p.m. eastern standard time, assuming eastern standard time is obeying daylight saving time.

Specifying the date-time values in UTC is useful if you do not know the time zone in which the orders or depots are located or when you have orders and depots in multiple time zones and you want all the date-time values to start simultaneously. The UTC option is applicable only when your network dataset defines a time zone attribute. Otherwise, all the date-time values are always treated as Geo local (GEO_LOCAL in Python).

String
overrides
(Optional)

Specifies additional settings that can influence the behavior of the solver when finding solutions for the network analysis problems.

The value for this parameter must be specified in JavaScript Object Notation (JSON). For example, a valid value is of the following form {"overrideSetting1" : "value1", "overrideSetting2" : "value2"}. The override setting name is always enclosed in double quotes. The values can be a number, Boolean, or string.

The default value for this parameter is no value, which indicates not to override any solver settings.

Overrides are advanced settings that should be used only after careful analysis of the results obtained before and after applying the settings. A list of supported override settings for each solver and their acceptable values can be obtained by contacting Esri Technical Support.

String
save_route_data
(Optional)

Specifies whether to save a .zip file that contains a file geodatabase containing the inputs and outputs of the analysis in a format that can be used to share route layers with ArcGIS Online or ArcGIS Enterprise.

In ArcGIS Desktop, the default output location for this output file is in the scratch folder. You can determine the location of the scratch folder using arcpy.env.scratchFolder.

  • SAVE_ROUTE_DATA The tool writes out a .zip archive containing a file geodatabase workspace that contains the inputs and outputs of the analysis.
  • NO_SAVE_ROUTE_DATARoute data is not saved. This is the default.
Boolean

Derived Output

NameExplanationData Type
solve_succeeded

A Boolean indicating whether solving the Vehicle Routing Problem analysis succeeded.

Boolean
out_unassigned_stops

Table that lists the orders that couldn't be visited by any routes.

Table
out_stops

Table that provides information about stops made at depots, orders, and breaks.

Table
out_routes

A feature class that represents the drivers, vehicles, and vehicle route paths in a vehicle routing problem.

Feature Class
out_directions

Turn-by-turn instructions to help drivers follow their assigned routes.

Feature Class
out_network_analysis_layer

Network analysis layer with properties configured in the tool parameters that can be used for further analysis or debugging in the map.

File
out_route_data

A .zip file containing all the information for a particular route.

File

Code sample

SolveVehicleRoutingProblem example 1 (Python window)

Execute the tool using only the required parameters.

import arcpy
orders = arcpy.FeatureSet()
orders.load("Stores")
depots = arcpy.FeatureSet()
depots.load("DistributionCenter")
routes = arcpy.RecordSet()
routes.load("RoutesTable")
arcpy.na.SolveVehicleRoutingProblem(orders, depots, routes, "","Minutes",
                                    "Miles", "Streets_ND")
SolveVehicleRoutingProblem example 2 (stand-alone script)

The following stand-alone Python script demonstrates how to use the SolveVehicleRoutingProblem tool to service a set of orders using a fleet of vehicles.

# Name: SolveVehicleRoutingProblem_Workflow.py
# Description: Find the best routes for a fleet of vehicles, which is operated 
#              by a distribution company, to deliver goods from a main 
#              distribution center to a set of grocery stores.
# Requirements: Network Analyst Extension 

#Import system modules
import arcpy
from arcpy import env
import datetime

try:
    #Check out Network Analyst license if available. Fail if the Network Analyst license is not available.
    if arcpy.CheckExtension("network") == "Available":
        arcpy.CheckOutExtension("network")
    else:
        raise arcpy.ExecuteError("Network Analyst Extension license is not available.")
    
    #Set environment settings
    env.workspace = "C:/data/SanFrancisco.gdb"
    env.overwriteOutput = True
    
    #Set local variables
    inNetworkDataset = "Transportation/Streets_ND"
    impedanceAttribute = "TravelTime"
    timeUnits = "Minutes"
    distanceUnits = "Miles"
    inOrders = "Analysis/Stores"
    inDepots = "Analysis/DistributionCenter"
    inRoutes = "RoutesTable"
    outGeodatabase = "C:\data\output\VRPOutputs.gdb"
    
    #Create two new feature sets and one record set with same schema as
    #Orders, Deopts and Routes parameter in Solve Vehicle Routing Problem tool.
    #Load the feature from the existing feature classes and table in the feature
    #set. Note that Solve Vehicle Routing Problem tool does not provide a way to
    #map field names between your input feature classes and table and the
    #feature set or record set parameters. To ensure that the attributes are
    #correctly transfered, the input feature classes and table must have same
    #field names as the feature sets and record sets.
    orders = arcpy.GetParameterValue("SolveVehicleRoutingProblem_na",0)    
    orders.load(inOrders)
    depots = arcpy.GetParameterValue("SolveVehicleRoutingProblem_na",1)    
    depots.load(inDepots)
    routes = arcpy.GetParameterValue("SolveVehicleRoutingProblem_na",2)    
    routes.load(inRoutes)
    
    #Call the SolveVRP tool and store the results in the result object
    result = arcpy.na.SolveVehicleRoutingProblem(orders,depots, routes,"",
                                                 timeUnits, distanceUnits,
                                                 inNetworkDataset, outGeodatabase,
                                                 populate_directions="DIRECTIONS")
    
    #print the solve status and output any warning messages from tool execution
    solveSucceeded = result.getOutput(0)
    print("Solve Succeeded: {0}".format(solveSucceeded))
    print("Messages from solver are printed below.")
    print(result.getMessages(1))
    
    print("Script completed successfully")

except Exception as e:
    # If an error occurred, print line number and error message
    import traceback, sys
    tb = sys.exc_info()[2]
    print("An error occurred on line %i" % tb.tb_lineno)
    print(str(e))

Licensing information

  • Basic: Requires Network Analyst
  • Standard: Requires Network Analyst
  • Advanced: Requires Network Analyst

Related topics