VehicleRoutingProblem
Summary
An ArcPy class for performing a vehicle routing problem analysis.
Discussion
A vehicle routing problem analysis allows you to calculate the best routes for a fleet of vehicles.
Learn more about vehicle routing problem analysis
Learn more about how to perform a network analysis using arcpy.nax
Syntax
VehicleRoutingProblem(in_network, {version})
| Name | Explanation | Data type |
|---|---|---|
|
in_network |
The network dataset or service that will be used for the network analysis. The argument can be specified using one of the following:
To use a network dataset, the network must have at least one travel mode. To use a portal URL, you must be signed in to the portal with an account that has routing privileges. Learn how to sign in to a portal in Python Learn more about network analysis using routing services When using ArcGIS Online or an ArcGIS Enterprise portal whose routing services are configured using ArcGIS Online as the Learn more about credit consumption and analysis limits in network analysis |
String |
|
version (Optional) |
The schema version to use in the analysis. The parameter should be specified using the An updated It is recommended that all new analyses use schema version The default is schema version |
Object |
Properties
| Name | Explanation | Data type |
|---|---|---|
|
allowAutoRelocate (Read and Write) |
Specifies whether inputs with existing network location fields can be automatically relocated at solve time to ensure valid, routable location fields for the analysis. If the value is Even if the value is The default is This property affects locating for all input types. To change this property for individual input types, use the Learn more about network location fields and how inputs are located on the network Setting this property returns an error if the network data source is ArcGIS Online, an ArcGIS Enterprise portal that does not support using network location fields, or a portal running a version of ArcGIS Enterprise earlier than 11.0. |
Boolean |
|
allowSaveLayerFile (Read and Write) |
Specifies whether saving the analysis result as a layer file using the |
Boolean |
|
allowSaveRouteData (Read and Write) |
Specifies whether route data will be generated. A value of The default is Caution:Even if this property is set to |
Boolean |
|
defaultDate (Read and Write) |
The default date for time field values that specify a time of day without including a date. The default is |
DateTime |
|
directionsDistanceUnits (Read and Write) |
The units that will be used when reporting travel distance in the output turn-by-turn directions. The property is returned and set as a member of the Note:The This parameter does not apply and is ignored when the analysis uses the |
Object |
|
directionsLanguage (Read and Write) |
The language in which the output turn-by-turn directions text will appear. The property is returned and set as a string using one of the two- or five-character language codes representing supported directions languages. The list of available directions languages can be obtained from the The property is applicable only when the |
String |
|
directionsStyle (Read and Write) |
The style that will be used for the output turn-by-turn directions text. The property is returned and set as a member of the The default value is This parameter does not apply and is ignored when the analysis uses the |
Object |
|
distanceUnits (Read and Write) |
The units that will be used when reporting the travel distance in the analysis output. Regardless of the units of the cost attributes in the network dataset, the output will be transformed to and reported in the units set in this property. The property is returned and set as a member of the Caution:The |
Object |
|
excessTransitFactor (Read and Write) |
Rates 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. The property is returned and set as a member of the When set to When set to When set to |
Object |
|
ignoreInvalidLocations (Read and Write) |
Specifies whether invalid input order locations will be ignored. A value of Note:This property applies only to orders. All other locations, such as depots, must always be valid or the analysis will fail. |
Boolean |
|
networkDataSource (Read only) |
The full catalog path to the network dataset or the URL of the service being used for the analysis. |
String |
|
overrides (Read and Write) |
Note:This property is for internal use only. |
String |
|
returnDirections (Read and Write) |
Specifies whether turn-by-turn directions will be generated. A value of |
Boolean |
|
returnStopShapes (Read and Write) |
Specifies whether point shapes will be generated for the output stops. When set to This parameter does not apply and is ignored when the analysis uses the Legacy:Routing services based on portals running versions of ArcGIS Enterprise earlier than 10.8 do not support returning stop shapes. The method returns a |
Boolean |
|
routeShapeType (Read and Write) |
The type of shape that will be generated to represent output routes. The routes are calculated along the network; however, you can represent them by shapes that do not reflect the network paths. The property is returned and set as a member of the The default is |
Object |
|
searchQuery (Read and Write) |
Legacy:This property has been superseded by the When locating inputs on the network, this property specifies a query to restrict the search to a subset of the features in a source feature class. This is useful if you don't want to find features that may be unsuited for a network location. For example, if you don't want to locate on highway ramps, you can define a query to exclude them. The property value is specified as a list with nested lists, with one entry per network source. Each inner list is composed of two values indicating the name of the network source and the SQL expression used as the query for that source. An empty string, For example, the value If a network source is not included in the list, it is interpreted to have no query. The value By default, no query is used for any source. Learn more about locating inputs on the network For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS. Setting this property returns an error if the network data source is ArcGIS Online or a portal running a version of ArcGIS Enterprise earlier than 11.0. |
List |
|
searchSources (Read and Write) |
When locating inputs on the network, this property specifies the list of network sources that will be used, and, optionally, a query to restrict the search to a subset of the features in a source feature class. The default value is to locate on all network sources except system junctions and override junctions created by running the Dissolve Network tool. By default, no query is used for any source. The property value is specified as a list with nested lists, with at most one entry per network source. Each inner list is composed of two values indicating the name of the network source and the SQL expression used as the query for that source. Possible values for the network source component are the string feature class names of edge and junction sources that participate in the network. Sources in the list will be used for locating, and sources not in the list will not. Queries are useful if you don't want to find features that may be unsuited for a network location. For example, if you don't want to locate on highway ramps, you can define a query to exclude them. For the query component, see SQL reference for query expressions used in ArcGIS for correct syntax. An empty string, For example, the value This property affects locating for all input types. To change this property for individual input types, use the Learn more about locating inputs on the network Setting this property returns an error if the network data source is ArcGIS Online or a portal running a version of ArcGIS Enterprise earlier than 11.0. |
String |
|
searchTolerance (Read and Write) |
The maximum search distance that will be used when locating the input features on the network. The property is returned and set as a double, and the units of this value are accessed through the This property affects locating for all input types. To change this property for individual input types, use the Learn more about locating inputs on the network Legacy:Setting this property returns an error if the network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0. |
Double |
|
searchToleranceUnits (Read and Write) |
Specifies the units of the This property affects locating for all input types. To change this property for individual input types, use the Legacy:Setting this property returns an error if the network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0. |
Object |
|
spatiallyClusterRoutes (Read and Write) |
Specifies whether assigned orders will be spatially clustered. When set to The default is |
Boolean |
|
timeUnits (Read and Write) |
Specifies the units that will be used when reporting the travel time in the analysis output. Regardless of the units of the cost attributes in the network dataset, the outputs will be transformed to and reported in the units set in this property. The property is returned and set as a member of the |
Object |
|
timeWindowFactor (Read and Write) |
Rates the importance of honoring time windows. The property is returned and set as a member of the When set to When set to When set to |
Object |
|
timeZoneForTimeFields (Read and Write) |
Specifies whether the time fields in the input data will be interpreted as local time at the input locations or as coordinated universal time (UTC). The property is returned and set as a member of the |
Object |
|
travelMode (Read and Write) |
The travel mode that will be used for the analysis. Vehicle Routing Problem analysis must use a time-based impedance, so only time-based impedance travel modes are available. The value is returned and set as an |
Object |
Methods
addFields(input_type, field_description[field_description,...])
Adds custom fields to the designated input class. These fields will be included in the field mapping dictionary created by the fieldMappings method and will also be available for use with the insertCursor method.
Learn more about using custom fields in analysis inputs
| Name | Explanation | Data type | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
input_type |
The type of input to which the fields will be added. Set this parameter using the |
Object |
||||||||||||||||||||||||
|
field_description[field_description,...] |
The fields and their properties that will be added to the input class. The value will be constructed as a list of lists with each row containing the following items:
Available field types are as follows:
Only the field name and type are required. Use None as a place holder for any of the other parameters to accept the default or if the parameter does not apply to the specified field type. The method will return an error if the field already exists in the table or if any of the field properties are invalid. Legacy:The |
TEXT |
count(input_type)
Returns the number of rows added for an input type.
| Name | Explanation | Data type |
|---|---|---|
|
input_type |
The type of input features to count. Set this parameter using the |
Object |
Return value
| Data type | Explanation |
|---|---|
|
Integer |
The number of rows. |
fieldMappings(input_type, {use_location_fields}, {list_candidate_fields[list_candidate_fields,...]})
Generates an NAClassFieldMappings dictionary that maps the field names of the input type to arcpy.nax.NAClassFieldMap objects that allow you to map fields from the input data to the properties of the solver. The dictionary can be used as input to the field_mappings argument of the load method.
Learn more about how to use field mappings when loading inputs
| Name | Explanation | Data type |
|---|---|---|
|
input_type |
The type of input for which the field mappings will be returned. Set this parameter using the Learn more about the fields available for each input type when using the |
Object |
|
use_location_fields (Optional) |
Specifies whether network location fields will be included in the returned field mappings dictionary. Network location fields describe the point on the network where an object is located. You can use network location fields to more precisely control how analysis inputs locate on the network and to save time when calling the Learn more about network location fields and how inputs are located on the network When this argument is set to The default value is False. |
Boolean |
|
list_candidate_fields[list_candidate_fields,...] (Optional) |
Use this parameter to map additional, nondefault fields from the input data to the analysis inputs. For example, if the input feature class contains a field named Specify this parameter as a list of Learn more about best practices for setting up analysis inputs Legacy:If the network data source is an ArcGIS Enterprise portal, the method will return an error if any of the fields specified are of a type that is not supported by the portal version. The default value is None. |
Field |
Return value
| Data type | Explanation |
|---|---|
|
Dictionary |
An |
fieldNames(input_type, {use_location_fields})
Get a list of field names supported by the specified input type.
| Name | Explanation | Data type |
|---|---|---|
|
input_type |
The type of input for which the supported field names are returned. Set this parameter using the Learn more about the fields available for each input type when using the |
Object |
|
use_location_fields (Optional) |
Indicates whether network location fields will be included in the returned list of field names. Network location fields describe the point on the network where an object is located. You can use network location fields to more precisely control how your analysis inputs locate on the network and to save time when calling the Learn more about network location fields and how inputs are located on the network When this argument is set to The default value is False. |
Boolean |
Return value
| Data type | Explanation |
|---|---|
|
String |
A list of field names supported by the specified input type. |
insertCursor(input_type, field_names[field_names,...], {append})
Establishes a write cursor on the specified input type. This cursor can be used to add rows directly to the input.
Learn more about how to insert inputs
| Name | Explanation | Data type |
|---|---|---|
|
input_type |
The type of input into which the cursor can be used to insert rows. Set this parameter using the |
Object |
|
field_names[field_names,...] |
A list of field names of the input type whose values you want to set when inserting rows using the cursor. You can get the names of the fields supported by an input type using the Learn more about the fields available for each input type when using the In addition to regular fields, you can also set the geometry of the input using one of the following geometry tokens:
The |
String |
|
append (Optional) |
Specifies whether the features being inserted will be appended to the existing set of features for the input type. A value of The default value is True. |
Boolean |
Return value
| Data type | Explanation |
|---|---|
|
Object |
A |
load(input_type, features, {field_mappings}, {append}, {max_features})
Sets input features to use for the analysis.
Learn more about how to load inputs
| Name | Explanation | Data type |
|---|---|---|
|
input_type |
The type of input feature that will be loaded. Set this parameter using the |
Object |
|
features |
The input features that will be loaded. This parameter accepts the following input types:
For layer inputs, only selected features will be loaded. If a layer has a definition query, only the subset of features visible with the definition query will be loaded. The method also honors the Extent geoprocessing environment; only features in the specified extent will be loaded. |
String |
|
field_mappings (Optional) |
An If no field mappings are specified, all fields from the input features that have the same name as the supported fields for the input type will be mapped. Learn more about the fields available for each input type when using the The default value is None. |
Dictionary |
|
append (Optional) |
Specifies whether the features being loaded will be appended to the existing set of features for the input type. A value of The default value is True. |
Boolean |
|
max_features (Optional) |
The maximum number of features that can be loaded into the input type. This is useful if you are creating a tool or service and want an error returned if the size of the input exceeds the available resources. The If no value is provided, no limit will be enforced for the count of the input features. The default value is None. |
Integer |
setLocateSettingsOverrides(input_type, {search_sources[[Source, Expression],...]}, {allow_auto_relocate}, {search_tolerance}, {search_tolerance_units})
Set locate settings for a designated input class, overriding the default locate settings specified for the analysis. This is useful if you want to use different rules to locate different inputs. For example, in an OD cost matrix analysis, you can use a search query that applies to the input origins only, if that query should not apply to the input destinations and barriers.
Using this method, you can override the values of the searchSources, allowAutoRelocate, searchTolerance, and searchToleranceUnits properties for the designated input class.
Learn more about locating inputs on the network
| Name | Explanation | Data type |
|---|---|---|
|
input_type |
The type of input for which to override default locate settings. Set this parameter using the Locate settings do not apply to table-based inputs and inputs that do not locate on the network. For the vehicle routing problem solver, only orders, depots, and barriers locate on the network and are valid input types for this method. The method returns an error if an inapplicable input type is specified. |
Object |
|
search_sources[[Source, Expression],...] (Optional) |
The list of network sources to be used when locating inputs of the designated type on the network, and, optionally, a query to restrict the search to a subset of the features within a source feature class. See the documentation for the Specifying a value for this parameter overrides the default If this parameter is not specified or is set to The method returns an error if this parameter is used and the network data source is ArcGIS Online. |
String |
|
allow_auto_relocate (Optional) |
Specifies whether inputs of the designated type with existing network location fields can be automatically relocated at solve time to ensure valid, routable location fields for the analysis. If the value is Even if the value is Specifying a value for this parameter overrides the default If this parameter is not specified or is set to The method returns an error if the network data source is ArcGIS Online. The method returns an error if the network data source is an ArcGIS Enterprise portal that does not support using network location fields. |
Boolean |
|
search_tolerance (Optional) |
The maximum search distance to use when locating inputs of the designated type on the network. Specifying a value for this parameter overrides the default If this parameter is not specified or is set to The units of this parameter value are set using the This parameter does not apply to line and polygon barriers; the method will return an error if this parameter is specified when the |
Double |
|
search_tolerance_units (Optional) |
The units of the maximum search distance when locating inputs of the designated type of the network. The parameter is specified using a member of the Specifying a value for this parameter overrides the default If this parameter is not specified or is set to The value specified using the This parameter does not apply to line and polygon barriers; the method will return an error if this parameter is specified when the |
Double |
solve()
Perform the vehicle routing problem analysis using the properties set on the VehicleRoutingProblem object and the loaded inputs.
Return value
| Data type | Explanation |
|---|---|
|
Object |
An |
Code sample
Perform a vehicle routing problem analysis.
# An example showing how to perform vehicle routing problem analysis using inputs from feature classes and tables.
import arcpy
nds = "C:/data/NorthAmerica.gdb/Routing/Routing_ND"
nd_layer_name = "Routing_ND"
input_orders = "C:/data/io.gdb/Orders"
input_depots = "C:/data/io.gdb/Depots"
input_routes = "C:/data/io.gdb/Vehicles"
output_stops = "C:/data/io.gdb/AssignedStops"
output_routes = "C:/data/io.gdb/Routes"
output_directions = "C:/data/io.gdb/Directions"
unassigned_stops = "C:/data/io.gdb/UnassignedStops"
# Create a network dataset layer and get the desired travel mode for analysis
arcpy.nax.MakeNetworkDatasetLayer(nds, nd_layer_name)
nd_travel_modes = arcpy.nax.GetTravelModes(nd_layer_name)
travel_mode = nd_travel_modes["Driving Time"]
# Instantiate a VehicleRoutingProblem solver object
vrp = arcpy.nax.VehicleRoutingProblem(nd_layer_name)
# Set properties
vrp.travelMode = travel_mode
vrp.distanceUnits = arcpy.nax.DistanceUnits.Miles
vrp.routeShapeType = arcpy.nax.RouteShapeType.TrueShape
vrp.returnDirections = True
vrp.returnStopShapes = True
# Load inputs
vrp.load(arcpy.nax.VehicleRoutingProblemInputDataType.Orders, input_orders)
vrp.load(arcpy.nax.VehicleRoutingProblemInputDataType.Depots, input_depots)
vrp.load(arcpy.nax.VehicleRoutingProblemInputDataType.Routes, input_routes)
# Solve the analysis
result = vrp.solve()
# Export the results to feature classes
if result.solveSucceeded:
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType.Stops, output_stops)
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType.Routes, output_routes)
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType.Directions, output_directions)
if result.isPartialSolution:
print("Some of the orders were not assigned.")
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType.UnassignedStops, unassigned_stops)
else:
print("Solved failed")
print(result.solverMessages(arcpy.nax.MessageSeverity.All))
Perform a vehicle routing problem analysis using the VehicleRoutingProblemSchemaVersion.Two schema version.
# An example showing how to perform vehicle routing problem analysis using inputs from feature classes and tables.
import arcpy
nds = "C:/data/NorthAmerica.gdb/Routing/Routing_ND"
nd_layer_name = "Routing_ND"
input_orders = "C:/data/io.gdb/Orders"
input_depots = "C:/data/io.gdb/Depots"
input_routes = "C:/data/io.gdb/Vehicles"
output_orders = "C:/data/io.gdb/VisitedOrders"
output_routes = "C:/data/io.gdb/Routes"
output_depots_visits = "C:/data/io.gdb/DepotVisits"
# Create a network dataset layer and get the desired travel mode for analysis
arcpy.nax.MakeNetworkDatasetLayer(nds, nd_layer_name)
nd_travel_modes = arcpy.nax.GetTravelModes(nd_layer_name)
travel_mode = nd_travel_modes["Driving Time"]
# Instantiate a VehicleRoutingProblem solver object using schema version Two
vrp = arcpy.nax.VehicleRoutingProblem(nd_layer_name, arcpy.nax.VehicleRoutingProblemSchemaVersion.Two)
# Set properties
vrp.travelMode = travel_mode
vrp.distanceUnits = arcpy.nax.DistanceUnits.Miles
vrp.routeShapeType = arcpy.nax.RouteShapeType.TrueShape
vrp.returnDirections = True
# Load inputs
vrp.load(arcpy.nax.VehicleRoutingProblemInputDataType2.Orders, input_orders)
vrp.load(arcpy.nax.VehicleRoutingProblemInputDataType2.Depots, input_depots)
vrp.load(arcpy.nax.VehicleRoutingProblemInputDataType2.Routes, input_routes)
# Solve the analysis
result = vrp.solve()
# Export the results to feature classes
if result.solveSucceeded:
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType2.Orders, output_orders)
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType2.Routes, output_routes)
result.export(arcpy.nax.VehicleRoutingProblemOutputDataType2.DepotVisits, output_depots_visits)
else:
print("Solve failed")
print(result.solverMessages(arcpy.nax.MessageSeverity.All))