Skip To Content

OriginDestinationCostMatrix

Summary

An ArcPy class for performing an origin destination cost matrix analysis.

Discussion

An origin destination cost matrix analysis allows you to calculate the travel time or distance along a network between a set of origins and a set of destinations.

Learn more about origin destination cost matrix analysis

Syntax

OriginDestinationCostMatrix (in_network)
ParameterExplanationData Type
in_network

The network dataset to use for the network analysis. The argument can be specified using the catalog path to the network dataset, a network dataset layer object, or the string name of the network dataset layer. The network dataset must have at least one travel mode.

String

Properties

PropertyExplanationData Type
accumulateAttributeNames
(Read and Write)

A list of cost attributes to be accumulated during analysis. These accumulated attributes are for reference only; the solver only uses the cost attribute used by your designated travel mode when solving the analysis.

The default is an empty list.

String
defaultDestinationCount
(Read and Write)

The maximum number of destinations to find per origin. The default is None, which means to find all destinations.

The value set in this property can be overridden on a per-origin basis using the TargetDestinationCount field in the input origins.

Integer
defaultImpedanceCutoff
(Read and Write)

The impedance value at which to stop searching for destinations from a given origin.

If the travel mode used in the analysis uses a time-based impedance attribute, the defaultImpedanceCutoff is interpreted in the units specified in the timeUnits property. If the travel mode used in the analysis uses a distance-based impedance attribute, the defaultImpedanceCutoff is interpreted in the units specified in the distanceUnits property. If the travel mode's impedance attribute is neither time-based nor distance-based, the defaultImpedanceCutoff value is interpreted in the units of the impedance attribute. The default is None, which means that no cutoff is applied.

The defaultImpedanceCutoff can be overridden on a per-origin basis using the Cutoff field in the input origins.

Double
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
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
lineShapeType
(Read and Write)

The type of linear shape to be generated to represent the output of the analysis. The travel time and distance are always calculated along the network; however, the linear output shapes represent the connections calculated between the input points in the analysis rather than the path through the network. The property is returned and set as a member of the LineShapeType enumeration. The default is LineShapeType.StraightLine.

Object
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 needs to 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 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
searchQuery
(Read and Write)

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.

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
timeOfDay
(Read and Write)

The time of day to use for the analysis. The default is None, which means that the analysis will be time neutral.

DateTime
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
timeZone
(Read and Write)

Indicates whether the time specified in the timeOfDay property will be interpreted as the 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 and is applicable only when the timeOfDay property is not None. The default is TimeZoneUsage.LocalTimeAtLocations.

Object
travelMode
(Read and Write)

The travel mode to use for the analysis.

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.

Learn more about travel modes

Object

Method Overview

MethodExplanation
fieldMappings (input_type, {use_location_fields}, {list_candidate_fields})

Generates a 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)

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 origin destination cost matrix analysis using the properties set on the OriginDestinationCostMatrix object and the loaded inputs.

Methods

fieldMappings (input_type, {use_location_fields}, {list_candidate_fields})
ParameterExplanationData Type
input_type

The type of input for which the field mappings are returned.

The parameter should be set using the OriginDestinationCostMatrixInputDataType enumeration.

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.

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,...]

A list of arcpy.Field objects used to generate the mapped field names, which can be obtained from a given feature class or table using the arcpy.ListFields function. Field names not already matching a field for the input type will also be returned in the map. Calling the load method with these extra fields will add them to the solver's input features so the fields can be passed through and included in the output. If this argument is not specified, the field mappings will be created with only the default values for the appropriate properties.

(The default value is None)

Field
Return Value
Data TypeExplanation
Dictionary

A dictionary in which the keys are the field name and values are arcpy.nax.NAClassFieldMap objects.

fieldNames (input_type, {use_location_fields})
ParameterExplanationData Type
input_type

The type of input for which the supported field names are returned.

The parameter should be set using the OriginDestinationCostMatrixInputDataType enumeration.

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.

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
Return Value
Data TypeExplanation
String

A list of field names supported by the specified input type.

insertCursor (input_type, field_names)
ParameterExplanationData Type
input_type

The type of input into which the cursor can be used to insert rows.

The parameter should be set using the OriginDestinationCostMatrixInputDataType enumeration.

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. In addition to regular fields, you can also set the geometry of the input using one of the following geometry tokens:

  • SHAPE@XYA tuple of the feature's centroid x,y coordinates.
  • SHAPE@XYZA tuple of the feature's centroid x,y,z coordinates. This token is only supported when the geometry is z-enabled.
  • SHAPE@JSON The Esri JSON string representing the geometry.
  • SHAPE@WKBThe well-known binary (WKB) representation for OGC geometry. It provides a portable representation of a geometry value as a contiguous stream of bytes.
  • SHAPE@WKTThe well-known text (WKT) representation for OGC geometry. It provides a portable representation of a geometry value as a text string.
  • SHAPE@A geometry object for the feature.

The SHAPE@XY and SHAPE@XYZ tokens are only supported for point-based input types.

String
Return Value
Data TypeExplanation
Object

A SolverInsertCursor object that can be used to write features.

load (input_type, features, {field_mappings}, {append}, {max_features})
ParameterExplanationData Type
input_type

The type of input feature to load.

The parameter should be set using the OriginDestinationCostMatrixInputDataType enumeration.

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

A 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 ()
Return Value
Data TypeExplanation
Object

An arcpy.nax.OriginDestinationCostMatrixResult object that can be used to access outputs and solver messages.

Code sample

OriginDestinationCostMatrix example

Perform origin destination cost matrix analysis.

# An example showing how to perform origin destination cost matrix analysis using inputs from feature classes.
import arcpy
arcpy.CheckOutExtension("network")

nds = "C:/data/NorthAmerica.gdb/Routing/Routing_ND"
nd_layer_name = "Routing_ND"
input_origins = "C:/data/io.gdb/Origins"
input_destinations = "C:/data/io.gdb/Destinations"
output_lines = "C:/data/io.gdb/ODCostMatrixLines"

# 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 OriginDestinationCostMatrix solver object
odcm = arcpy.nax.OriginDestinationCostMatrix(nd_layer_name)
# Set properties
odcm.travelMode = travel_mode
odcm.timeUnits = arcpy.nax.TimeUnits.Minutes
odcm.defaultImpedanceCutoff = 15
odcm.defaultDestinationCount = 5
odcm.lineShapeType = arcpy.nax.LineShapeType.NoLine
# Load inputs
odcm.load(arcpy.nax.OriginDestinationCostMatrixInputDataType.Origins, input_origins)
odcm.load(arcpy.nax.OriginDestinationCostMatrixInputDataType.Destinations, input_destinations)
# Solve the analysis
result = odcm.solve()

# Export the results to a feature class
if result.solveSucceeded:
    result.export(arcpy.nax.OriginDestinationCostMatrixOutputDataType.Lines, output_lines)
else:
    print("Solved failed")
    print(result.solverMessages(arcpy.nax.MessageSeverity.All))