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.
Syntax
VehicleRoutingProblem (in_network, {version})| Parameter | Explanation | Data Type |
in_network | The network dataset or service that will be used for the network analysis. The argument can be specified using the catalog path to the network dataset, a network dataset layer object, the string name of the network dataset layer, or a portal URL for a network analysis service. 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. Solving an analysis will consume credits when the object uses ArcGIS Online as the in_network. For more information, see Service Credits Overview | String |
version | The schema version to use in the analysis. The parameter should be specified using the VehicleRoutingProblemSchemaVersion enumeration. An updated VehicleRoutingProblem object schema was introduced in ArcGIS Pro 2.7 to provide enhanced usability and to more closely match the schema of Vehicle Routing Problem layers introduced in ArcGIS Pro 2.6. It is recommended that all new analyses use schema version Two when possible. However, the schema version Two is not currently supported for portal URL network data sources. If the analysis will use a portal URL for the network data source or the script needs to be compatible with software versions prior to ArcGIS Pro 2.7, use schema version One. The default is schema version One. | Object |
Properties
| Property | Explanation | Data Type |
| allowSaveLayerFile (Read and Write) | Specifies whether to permit saving the analysis result as a layer file using the saveAsLayerFile method on the result object. A value of True means that you can save a layer file. A value of False means that you cannot. The default is True if the analysis references a network dataset and False if it references a portal service. Allowing a layer file to be saved may slow down the analysis when the analysis references a portal service. | Boolean |
| allowSaveRouteData (Read and Write) | Specifies whether to permit saving the analysis result to a ZIP file using the saveRouteData method on the result object. A value of True means that you can save the route data. A value of False means that you cannot. The default is True if the analysis references a network dataset and False if it references a portal service. Allowing the route data to be saved may slow down the analysis when the analysis references a portal service. | 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 None, which indicates that all date time fields include date and time values. | DateTime |
| directionsDistanceUnits (Read and Write) | The units to use when reporting travel distance in the output turn-by-turn directions. The property is returned and set as a member of the DistanceUnits enumeration and is applicable only when the returnDirections property is True. The default is the units of the distance attribute in the travel mode used for the analysis. | 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 arcpy.nax.ListDirectionsLanguages function. The default value is either en (English) or the language of the currently activated language pack. The property is applicable only when the returnDirections property is True. | String |
| directionsStyle (Read and Write) | The style to be used for the output turn-by-turn directions text. The property is returned and set as a member of the DirectionsStyle enumeration and is applicable only when the returnDirections property is True. The default value is Desktop. | Object |
| distanceUnits (Read and Write) | The units to use 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 DistanceUnits enumeration. The default is DistanceUnits.Kilometers. | 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 Importance enumeration. The default is Importance.Medium. When set to Importance.Low, the solver tries to find a solution that minimizes overall solution cost, regardless of excess transit time. This setting is commonly used with 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. When set to Importance.Medium, the solver looks for a balance between reducing excess transit time and reducing the overall solution cost. When set to Importance.High, the solver tries to find a solution with the least excess transit time between paired orders at the expense of increasing 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. | Object |
| ignoreInvalidLocations (Read and Write) | Specifies whether invalid input locations will be ignored. A value of True indicates that invalid input locations will be ignored so that the analysis will succeed using only valid locations. A value of False indicates that invalid locations will not be ignored and will cause the analysis to fail. | Boolean |
| networkDataSource (Read Only) | The full catalog path to the network dataset used for the analysis. | String |
| overrides (Read and Write) | Specify 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 quotation marks. The values can be either a number, Boolean, or string. The default value for this parameter is no value, which indicates to not 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 |
| returnDirections (Read and Write) | Specifies whether turn-by-turn directions will be generated. A value of True means that turn-by-turn directions will be generated when solving the analysis. A value of False means that directions will not be generated. Generating directions may slow down the analysis. The default is False. | Boolean |
| returnStopShapes (Read and Write) | When set to True, the solver generates point shapes for the output stops. When set to False, the output stops are returned in table format. The default is False. This parameter does not apply and is ignored when the analysis uses the VehicleRoutingProblemSchemaVersion.Two schema version. Legacy:Routing services based on portals running versions of ArcGIS Enterprise older than 10.8 do not support returning stop shapes. The method returns a ValueError exception if you set returnStopShapes to True, and the service does not support this option. | Boolean |
| routeShapeType (Read and Write) | The type of shape to be generated to represent output routes. The routes are always calculated along the network; however, you can choose to represent them by shapes that do not reflect the network paths. The property is returned and set as a member of the RouteShapeType enumeration. The default is RouteShapeType.TrueShapeWithMeasures. | Object |
| searchQuery (Read and Write) | When locating inputs on the network, specifies a query to restrict the search to a subset of the features within 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 are loading centroids of polygons and don't want to locate on local roads, you can define a query that searches for major roads only. Learn more about locating inputs on the network The parameter value is specified as a list with nested lists. The nested list is composed of two values indicating the name and the SQL expression for all of the network sources. The syntax for the SQL expression differs slightly depending on the type of the network source feature class. For example, if you're querying source feature classes stored in file or enterprise geodatabases, shapefiles, or SDC, enclose field names in double quotation marks: "CFCC". If you're querying source feature classes stored in personal geodatabases, enclose fields in square brackets: [CFCC]. If you don't want to specify a query for a particular source, use "#" as the value for the SQL expression or exclude the source name and the SQL expression from the parameter value. If you don't want to specify a query for all of the network sources, use "#" as the parameter value. For example, the parameter value [["Streets","\"CFCC\" = 'A15'"], ["Streets_ND_Junctions",""]] specifies an SQL expression for the Streets source feature class and no expression for the Streets_ND_Junctions source feature class. Note that the double quotation marks used to enclose the field name CFCC are escaped using backslash characters to avoid a parsing error from the Python interpreter. By default, no query is used. | List |
| searchTolerance (Read and Write) | The maximum search distance to use 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 searchToleranceUnits property. The default is 5000. | Double |
| searchToleranceUnits (Read and Write) | The units of the searchTolerance property. The property is returned and set as a member of the DistanceUnits enumeration. The default is DistanceUnits.Meters. | Object |
| spatiallyClusterRoutes (Read and Write) | When set to True, the orders assigned to a 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. When set to False, the solver will not prioritize spatially clustering orders, and the route lines might intersect. Use this option if route zones are specified. The default is True. | Boolean |
| timeUnits (Read and Write) | The units to use 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 TimeUnits enumeration. The default is TimeUnits.Minutes. | Object |
| timeWindowFactor (Read and Write) | Rates the importance of honoring time windows. The property is returned and set as a member of the Importance enumeration. The default is Importance.Medium. When set to Importance.Low, the solver places 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. When set to Importance.Medium, the solver balances the importance of minimizing drive times and arriving within time windows. When set to Importance.High, the solver places more importance on arriving at stops on time than on minimizing drive times. Organizations that make time-critical deliveries or that are very concerned with customer service would choose this setting. | Object |
| timeZoneForTimeFields (Read and Write) | Indicates whether the time fields in the input data should 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 TimeZoneUsage enumeration. The default is TimeZoneUsage.LocalTimeAtLocations. | Object |
| travelMode (Read and Write) | The travel mode to use for the analysis. VRP only solves with a time-based impedance, so only time-based impedance travel modes are available. The value is returned and set as an arcpy.nax.TravelMode object, but it can also be set using the string name of the travel mode or a string containing the valid JSON representation of a travel mode. The default is the default travel mode defined on the network dataset used for the analysis. | Object |
Method Overview
| Method | Explanation |
| addFields (input_type, 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. |
| count (input_type) |
Returns the number of rows added for an input type. |
| fieldMappings (input_type, {use_location_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 your input data to the properties of the solver. The dictionary can be used as input to the load method's field_mappings argument. |
| fieldNames (input_type, {use_location_fields}) | Get a list of field names supported by the specified input type. |
| insertCursor (input_type, field_names, {append}) | Establishes a write cursor on the specified input type. This cursor can be used to add rows directly to the input. |
| load (input_type, features, {field_mappings}, {append}, {max_features}) | Set input features to use for the analysis. |
| solve () | Perform the vehicle routing problem analysis using the properties set on the VehicleRoutingProblem object and the loaded inputs. |
Methods
addFields (input_type, field_description)
| Parameter | Explanation | Data Type |
input_type |
The type of input to which the fields should be added. The parameter should be set using the VehicleRoutingProblemInputDataType enumeration when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemInputDataType2 enumeration when using the VehicleRoutingProblemSchemaVersion.Two schema version. | Object |
field_description [field_description,...] |
The fields and their properties that will be added to the input class. The value should be constructed as a list of lists with each row containing the following items:
Available field types are as follows:
The method will return an error if the field already exists in the table or if any of the field properties are invalid. | List |
count (input_type)
| Parameter | Explanation | Data Type |
input_type | The type of input features to count. The parameter should be set using the VehicleRoutingProblemInputDataType enumeration when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemInputDataType2 enumeration when using the VehicleRoutingProblemSchemaVersion.Two schema version. | Object |
| Data Type | Explanation |
| Integer | The number of rows. |
fieldMappings (input_type, {use_location_fields}, {list_candidate_fields})| Parameter | Explanation | Data Type |
input_type | The type of input for which the field mappings are returned. The parameter should be set using the VehicleRoutingProblemInputDataType enumeration when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemInputDataType2 enumeration when using the VehicleRoutingProblemSchemaVersion.Two schema version. See descriptions of the fields available for each input type when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemSchemaVersion.Two schema version. | Object |
use_location_fields | Indicates whether network location fields should 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 your analysis inputs locate on the network and to save time when calling the solve method because the solver will not have to calculate the location fields from the geometry of the inputs. You can calculate location fields for a feature class using the Calculate Locations tool. Learn more about network location fields and how inputs are located on the network When this argument is set to True, the returned field mappings dictionary will contain network location fields. The default is False; the field mapping dictionary will not include network location fields. (The default value is False) | Boolean |
list_candidate_fields [list_candidate_fields,...] | Use this parameter to map additional, non-default fields from your input data into your analysis inputs. For example, if your input feature class contains a field named MyField, and you want this field to be included in your analysis inputs, pass the MyField field object to the list_candidate_fields parameter. MyField will be included in the returned field mapping dictionary and automatically mapped. When you call the load method using these field mappings, MyField will be included in the analysis inputs along with all the default fields. In many cases, these extra fields will be passed to the analysis output as well. The parameter should be specified as a list of arcpy.Field objects, which can be obtained from a given feature class or table using the arcpy.ListFields function. Learn more about best practices for setting up analysis inputs (The default value is None) | Field |
| Data Type | Explanation |
| Dictionary | An NAClassFieldMappings dictionary in which the keys are the field names and values are arcpy.nax.NAClassFieldMap objects. |
fieldNames (input_type, {use_location_fields})| Parameter | Explanation | Data Type |
input_type | The type of input for which the supported field names are returned. The parameter should be set using the VehicleRoutingProblemInputDataType enumeration when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemInputDataType2 enumeration when using the VehicleRoutingProblemSchemaVersion.Two schema version. See descriptions of the fields available for each input type when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemSchemaVersion.Two schema version. | Object |
use_location_fields | 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 solve method because the solver will not have to calculate the location fields from the geometry of the inputs. You can calculate location fields for a feature class using the Calculate Locations tool. Learn more about network location fields and how inputs are located on the network When this argument is set to True, the returned list of field names will contain network location fields. The default is False; the list of field names will not include network location fields. (The default value is False) | Boolean |
| Data Type | Explanation |
| String | A list of field names supported by the specified input type. |
insertCursor (input_type, field_names, {append})| Parameter | Explanation | Data Type |
input_type | The type of input into which the cursor can be used to insert rows. The parameter should be set using the VehicleRoutingProblemInputDataType enumeration when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemInputDataType2 enumeration when using the VehicleRoutingProblemSchemaVersion.Two schema version. | 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 by using the fieldNames method. See descriptions of the fields available for each input type when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemSchemaVersion.Two schema version. In addition to regular fields, you can also set the geometry of the input using one of the following geometry tokens:
The SHAPE@XY and SHAPE@XYZ tokens are only supported for point-based input types. When using the SHAPE@XY and SHAPE@XYZ tokens, the x-, y-, and z-values should be specified in the spatial reference of the network data source being used in the analysis. | String |
append | Specifies whether the features being inserted should be appended to the existing set of features for the input type. A value of True indicates that the new features should be appended; the existing features will be preserved. This is the default. A value of False indicates that any existing features for the input type should be deleted and replaced with the features currently being inserted. (The default value is True) | Boolean |
| Data Type | Explanation |
| Object | A SolverInsertCursor object that can be used to write features. |
load (input_type, features, {field_mappings}, {append}, {max_features})| Parameter | Explanation | Data Type |
input_type | The type of input feature to load. The parameter should be set using the VehicleRoutingProblemInputDataType enumeration when using the VehicleRoutingProblemSchemaVersion.One schema version or the VehicleRoutingProblemInputDataType2 enumeration when using the VehicleRoutingProblemSchemaVersion.Two schema version. | Object |
features | The input features to load. 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 | An NAClassFieldMappings dictionary that maps the field names of the input type to arcpy.nax.NAClassFieldMap objects representing the mapping of fields from the input features. Valid input for this parameter can be constructed using the fieldMappings method. If field mappings are not specified, all fields from the input features that have the same name as the supported fields for the input type will be mapped. (The default value is None) | Dictionary |
append | Indicates whether the features being loaded should be appended to the existing set of features for the input type. A value of True indicates that the new features should be appended; the existing features will be preserved. This is useful if you want to load inputs from multiple feature classes or tables to use in a single analysis. This is the default. A value of False indicates that any existing features for the input type should be deleted and replaced with the features currently being loaded. (The default value is True) | Boolean |
max_features | 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 load method will return an arcpy.nax.LimitError if the number of input features exceeds the max_features limit. If a value is not specified, no limit is enforced for the count of the input features. (The default value is None) | Integer |
solve ()
| Data Type | Explanation |
| Object | An arcpy.nax.VehicleRoutingProblemResult object that can be used to access outputs and solver messages. |
Code sample
Perform vehicle routing problem analysis.
# An example showing how to perform vehicle routing problem analysis using inputs from feature classes and tables.
import arcpy
arcpy.CheckOutExtension("network")
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(nds)
# 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 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
arcpy.CheckOutExtension("network")
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(nds, 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))