Calculate Locations (Network Analyst)

Summary

Locates input features on a network and adds fields to the input features that describe the network locations. The tool is used to precalculate the network locations of inputs that will be used in a Network Analyst workflow, improving performance of the analysis at solve time. The tool stores the calculated network locations of the inputs in fields in the input data.

Learn more about locating features on a network

Learn more about precalculating network locations

Usage

• By default, this tool stores the calculated network locations in a set of fields with network location field names recognized by all Network Analyst workflows. However, you can change the names of the fields where the calculated network locations are stored. In this case, when using the precalculated network locations in a workflow, use field mapping to map the nondefault location fields to the correct network location properties.

  The only reason to change the field names is to store a separate set of location fields for different networks or travel modes in the same feature class. Otherwise, always use the default field names.

  Alternate field names can be specified using the Source ID Field, Source OID Field, Percent Along Field, Side of Edge Field, Located X-Coordinate Field, Located Y-Coordinate Field, Distance from Feature Field, Located Z-Coordinate Field, and Location Ranges Field parameters.

• This tool only calculates the network locations of inputs using a network dataset. It cannot calculate network locations for a network analysis service.

• If the input features are a sublayer of a network analysis layer, the Search Tolerance, Search Criteria, and Search Query parameters are automatically populated based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings are used. Otherwise, the network analysis layer's default location settings are used.

  Learn more about a network analysis layer's location settings

• If the input features are a sublayer of a network analysis layer and you change the value for the Search Tolerance, Search Criteria, or Search Query parameters, running the tool will update the network analysis layer's location settings overrides for the selected sublayer. Storing these location settings in the network analysis layer ensures that any automatic relocating done at solve time uses the same location settings you used when initially calculating network locations.

• If the input feature class has a CurbApproach field of type Long, the values in this field may be used to influence locating behavior. In particular, if points locate on a one-way street and have a curb approach specifying the left or right side of the vehicle, the SideOfEdge location field value may be updated to ensure that the point can be reached in the correct direction along the one-way street. The CurbApproach field is not required in the input, but if it exists and is of type Long, it will be used.

  If a row has a CurbApproach field value that doesn't match one of the valid CurbApproach domain values, the field value for that row will be ignored when locating the point and the default value of 0 (either side of vehicle) will be used.

  Learn more about curb approach

• If the input feature class has a Status field of type Long, the field's values will be updated to reflect each row's locating status.

  If the Status field in the input feature class is used for another purpose and you don't want it to be overwritten, change the field's name before running this tool.

Parameters

Dialog

Label	Explanation	Data Type
Input Features	The input features for which the network locations will be calculated. For line and polygon features, since the network location information is stored in a BLOB field, only geodatabase feature classes are supported.	Table View
Input Analysis Network (Optional)	The network dataset that will be used to calculate the locations. This parameter is required unless a sublayer of a network analysis layer is used as input features. In that case, the parameter is hidden and automatically set to the network dataset referenced by the network analysis layer.	Network Dataset Layer
Search Tolerance (Optional)	The maximum search distance that will be used when locating the input features on the network. Features that are outside the search tolerance will be left unlocated. The parameter includes a value and units. The default is 5000 meters. If the input features are a sublayer of a network analysis layer, the default value for this parameter is determined based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings will be used. Otherwise, the network analysis layer's default location settings will be used. Setting a nondefault value for this parameter updates the network analysis layer's location settings overrides for the selected sublayer. The parameter is not used when calculating locations for line or polygon features.	Linear Unit
Search Criteria (Optional)	The edge and junction sources in the network dataset that will be searched when locating inputs on the network. For example, if the network dataset references separate feature classes representing streets and sidewalks, you can locate inputs on streets but not on sidewalks. The following are the available snap type options for each network source: None—The point will not locate on elements in this network source. Shape—The point will locate on the closest point of an element in this network source. Middle—This option is deprecated and behaves the same as Shape. End—This option is deprecated and behaves the same as Shape. The default value is to locate on all network sources except override junctions created by running the Dissolve Network tool and system junctions. If the input features are a sublayer of a network analysis layer, the default value for this parameter is determined based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings will be used. Otherwise, the network analysis layer's default location settings will be used. Setting a nondefault value for this parameter updates the network analysis layer's location settings overrides for the selected sublayer.	Value Table
Find Closest among All Classes (Optional)	Legacy: This parameter is deprecated and maintained only for backward compatibility. Inputs will always be matched to the closest network source among all the sources used for locating, corresponding to a parameter value of MATCH_TO_CLOSEST or True.	Boolean
Source ID Field (Optional)	The name of the field to be created or updated that will be populated with the ID of the network dataset source feature class for the input feature's computed network location. The default value is SourceID. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Source OID Field (Optional)	The name of the field to be created or updated that will be populated with the ObjectID field value of the network dataset source feature class for the input feature's computed network location. The default value is SourceOID. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Percent Along Field (Optional)	The name of the field to be created or updated describing the computed network location's percent along the network element where it was located. The default value is PosAlong. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Side of Edge Field (Optional)	The name of the field to be created or updated describing the side of the network edge where the computed network location is located. The default value is SideOfEdge. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Located X-Coordinate Field (Optional)	The name of the field to be created or updated with the x-coordinate of the computed network location. The default value is SnapX. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Located Y-Coordinate Field (Optional)	The name of the field to be created or updated with the y-coordinate of the computed network location. The default value is SnapY. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Distance from Feature Field (Optional)	The name of the field to be created or updated describing the distance in meters of the original point feature from its computed network location. The default value is DistanceToNetworkInMeters. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Located Z-Coordinate Field (Optional)	The name of the field to be created or updated with the z-coordinate of the computed network location. The default value is SnapZ. The parameter is used only when the input network dataset supports connectivity based on z-coordinate values of the network sources. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Location Ranges Field (Optional)	The name of the field to be created or updated with the location ranges of the computed network locations for line or polygon features. The default value is Locations. The parameter is used only when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
Exclude Restricted Portions of the Network (Optional)	Legacy: This parameter is deprecated and maintained only for backward compatibility. Analysis inputs will never be located on network elements that are restricted, corresponding to a parameter value of EXCLUDE or True.	Boolean
Search Query (Optional)	A query that restricts 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 don't want to locate on highway ramps, you can define a query to exclude them. A separate SQL expression can be specified per edge or junction source feature class of the network dataset. Any network source not explicitly specified in the Geoprocessing pane will have no query applied. By default, no query is used for any source. If the input features are a sublayer of a network analysis layer, the default value for this parameter is determined based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings will be used. Otherwise, the network analysis layer's default location settings will be used. Setting a nondefault value for this parameter updates the network analysis layer's location settings overrides for the selected sublayer.	Value Table
Travel Mode (Optional)	The name of the travel mode that will be used. If you specify a travel mode, the travel mode settings, such as restrictions and impedance attributes, will be considered when calculating network location. For example, if the closest network edge to one of the input points is restricted when the selected travel mode is applied, the tool will locate the point on the next-closest network edge that is not restricted. The available travel modes depend on the Input Analysis Network parameter value. If a sublayer of a network analysis layer is used as input features, this parameter is hidden and should not be used. When network locations are calculated, the network analysis layer's current travel mode will automatically be used.	String

Derived Output

Label	Explanation	Data Type
Updated Input Features	The updated input features.	Table View
Network Analyst Layer	If the Input Features parameter value was a sublayer of a network analysis layer, this derived output parameter returns the sublayer's parent network analysis layer. Otherwise, no value is returned.	Network Analyst Layer

Python

arcpy.management.CalculateLocations(in_point_features, {in_network_dataset}, {search_tolerance}, {search_criteria}, {match_type}, {source_ID_field}, {source_OID_field}, {position_field}, {side_field}, {snap_X_field}, {snap_Y_field}, {distance_field}, {snap_Z_field}, {location_field}, {exclude_restricted_elements}, {search_query}, {travel_mode})

Name	Explanation	Data Type
in_point_features	The input features for which the network locations will be calculated. For line and polygon features, since the network location information is stored in a BLOB field, only geodatabase feature classes are supported.	Table View
in_network_dataset (Optional)	The network dataset that will be used to calculate the locations. This parameter is required unless a sublayer of a network analysis layer is used as input features. In that case, don't specify a value for this parameter or set it to the network dataset referenced by the network analysis layer.	Network Dataset Layer
search_tolerance (Optional)	The maximum search distance that will be used when locating the input features on the network. Features that are outside the search tolerance will be left unlocated. The parameter includes a value and units. The default is 5000 meters. If the input features are a sublayer of a network analysis layer, the default value for this parameter is determined based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings will be used. Otherwise, the network analysis layer's default location settings will be used. Setting a nondefault value for this parameter updates the network analysis layer's location settings overrides for the selected sublayer. The parameter is not used when calculating locations for line or polygon features.	Linear Unit
search_criteria [[Source, SnapType],...] (Optional)	The edge and junction sources in the network dataset that will be searched when locating inputs on the network. For example, if the network dataset references separate feature classes representing streets and sidewalks, you can locate inputs on streets but not on sidewalks. The parameter value is specified as a list with nested lists. The nested lists are composed of two values indicating the name and snap type of each network source. The following are the available snap type options for each network source: NONE—The point will not locate on elements in this network source. SHAPE—The point will locate on the closest point of an element in this network source. For example, a parameter value of [["Streets","SHAPE"],["Streets_ND_Junctions","NONE"]] specifies that the search can locate on the shape of the Streets source but not on the Streets_ND_Junctions source. Any network edge or junction source that is not included in this list will use its default snap type. It is recommended that you include all network sources in your list and explicitly set the snap type for each. Legacy: Historically, the tool supported the snap type options MIDDLE, END, and MIDDLE_END. These options are deprecated and maintained for backward compatibility only. If one of these options is specified, the tool reverts to the SHAPE option for that network source. The default value is to locate on all network sources except override junctions created by running the Dissolve Network tool and system junctions. If the input features are a sublayer of a network analysis layer, the default value for this parameter is determined based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings will be used. Otherwise, the network analysis layer's default location settings will be used. Setting a nondefault value for this parameter updates the network analysis layer's location settings overrides for the selected sublayer.	Value Table
match_type (Optional)	Legacy: This parameter is deprecated and maintained only for backward compatibility. Inputs will always be matched to the closest network source among all the sources used for locating, corresponding to a parameter value of MATCH_TO_CLOSEST or True.	Boolean
source_ID_field (Optional)	The name of the field to be created or updated that will be populated with the ID of the network dataset source feature class for the input feature's computed network location. The default value is SourceID. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
source_OID_field (Optional)	The name of the field to be created or updated that will be populated with the ObjectID field value of the network dataset source feature class for the input feature's computed network location. The default value is SourceOID. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
position_field (Optional)	The name of the field to be created or updated describing the computed network location's percent along the network element where it was located. The default value is PosAlong. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
side_field (Optional)	The name of the field to be created or updated describing the side of the network edge where the computed network location is located. The default value is SideOfEdge. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
snap_X_field (Optional)	The name of the field to be created or updated with the x-coordinate of the computed network location. The default value is SnapX. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
snap_Y_field (Optional)	The name of the field to be created or updated with the y-coordinate of the computed network location. The default value is SnapY. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
distance_field (Optional)	The name of the field to be created or updated describing the distance in meters of the original point feature from its computed network location. The default value is DistanceToNetworkInMeters. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
snap_Z_field (Optional)	The name of the field to be created or updated with the z-coordinate of the computed network location. The default value is SnapZ. The parameter is used only when the input network dataset supports connectivity based on z-coordinate values of the network sources. The parameter is not used when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
location_field (Optional)	The name of the field to be created or updated with the location ranges of the computed network locations for line or polygon features. The default value is Locations. The parameter is used only when calculating locations for line or polygon features. Do not use this parameter when the input features are a sublayer of a network analysis layer. Network locations in a sublayer must be stored in location fields with the default names or they will not be used when the layer is solved.	Field
exclude_restricted_elements (Optional)	Legacy: This parameter is deprecated and maintained only for backward compatibility. Analysis inputs will never be located on network elements that are restricted, corresponding to a parameter value of EXCLUDE or True.	Boolean
search_query [[Source, Expression],...] (Optional)	A query that restricts 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 don't want to locate on highway ramps, you can define a query to exclude them. A separate SQL expression can be specified per edge or junction source feature class of the network dataset. The parameter 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, "", indicates no query for a particular source. For example, the value [["Streets", "ROAD_CLASS <> 3"], ["Streets_ND_Junctions", ""]] specifies an SQL expression for the Streets source feature class and no expression for the Streets_ND_Junctions source feature class. If a network source is not included in the list, it is interpreted to have no query. The value [["Streets", "ROAD_CLASS <> 3"]] is equivalent to [["Streets", "ROAD_CLASS <> 3"], ["Streets_ND_Junctions", ""]]. For more information about SQL syntax, see SQL reference for query expressions used in ArcGIS. By default, no query is used for any source. If the input features are a sublayer of a network analysis layer, the default value for this parameter is determined based on location properties stored in the input network analysis layer. If the network analysis layer has location settings overrides for the selected sublayer, those settings will be used. Otherwise, the network analysis layer's default location settings will be used. Setting a nondefault value for this parameter updates the network analysis layer's location settings overrides for the selected sublayer.	Value Table
travel_mode (Optional)	The name of the travel mode that will be used. If you specify a travel mode, the travel mode settings, such as restrictions and impedance attributes, will be considered when calculating network location. For example, if the closest network edge to one of the input points is restricted when the selected travel mode is applied, the tool will locate the point on the next-closest network edge that is not restricted. The available travel modes depend on the in_network_dataset parameter value. An arcpy.na.TravelMode object and a string containing the valid JSON representation of a travel mode can also be used as input to this parameter. If a sublayer of a network analysis layer is used as input features, do not set a value for this parameter. When network locations are calculated, the network analysis layer's current travel mode will automatically be used.	String

Derived Output

Name	Explanation	Data Type
out_point_feature_class	The updated input features.	Table View
output_layer	If the in_point_features parameter value was a sublayer of a network analysis layer, this derived output parameter returns the sublayer's parent network analysis layer. Otherwise, no value is returned.	Network Analyst Layer

Code sample

CalculateLocations example 1 (Python window)

Calculate locations for point features.

stores = "C:/Data/SanFrancisco.gdb/Analysis/Hospitals/Analysis/Stores"
network = "C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
arcpy.na.CalculateLocations(stores, network, "5000 Meters",
                            [["Streets", "SHAPE"],
                            ["Streets_ND_Junctions", "NONE"]])

CalculateLocations example 2 (Workflow)

The following code sample demonstrates using the CalculateLocations function to precalculate network locations and using those precalculated network locations in an arcpy.nax workflow.

The use_location_fields parameter in the fieldMappings method is set to True to ensure that the precalculated network location fields are used when the analysis inputs are loaded. Additionally, the network location fields are calculated using the same network dataset, travel mode, and location settings that are used in the service area analysis to ensure that the results are valid and consistent.

"""Precalculate network locations with the Calculate Locations
geoprocessing tool, then run a Service Area workflow using
the arcpy.nax solver object. Map the precalculated network
locations using fieldMappings and load.
"""
import arcpy

arcpy.CheckOutExtension("network")

network = "C:/Data/Paris.gdb/Transportation/ParisMultimodal_ND"
input_facilities = "C:/Data/Paris.gdb/Analysis/Stores"
travel_mode = "Driving Time"

# Make a network dataset layer
nd_layer = arcpy.nax.MakeNetworkDatasetLayer(network).getOutput(0)

# Run Calculate Locations to calculate the network locations of
# the points in the input feature class. Use the same network,
# travel mode, and locate settings that will be used in the
# network analysis.
# Set a search_tolerance of 500 meters.
# Use search_criteria to locate only on streets and metro entrances.
# Use search_query to prevent locating on highways (FUNC_CLASS 1)
arcpy.nax.CalculateLocations(
    input_facilities,
    nd_layer,
    search_tolerance="500 Meters",
    search_criteria=[
        ["Streets", "SHAPE"],
        ["Metro_Lines", "NONE"],
        ["Transfer_Stations", "NONE"],
        ["Transfer_Street_Station", "NONE"],
        ["Metro_Entrances", "SHAPE"],
        ["Metro_Stations", "NONE"],
        ["ParisMultimodal_ND_Junctions", "NONE"]
    ],
    search_query=[["Streets", "FUNC_CLASS <> '1'"]],
    travel_mode=travel_mode
)

# Initialize the Service Area solver object
service_area = arcpy.nax.ServiceArea(nd_layer)

# Set the analysis properties. Use the same travel mode and
# locate settings that were used when precalculating the
# network locations
service_area.travelMode = travel_mode
service_area.searchTolerance = 500
service_area.searchToleranceUnits = arcpy.nax.DistanceUnits.Meters
service_area.searchSources = [
    ["Streets", "FUNC_CLASS <> '1'"],
    ["Metro_Entrances", "SHAPE"]
]
service_area.defaultImpedanceCutoffs = [5, 10]

# Construct a field mapping object with network location fields
field_mappings = service_area.fieldMappings(
    arcpy.nax.ServiceAreaInputDataType.Facilities,
    use_location_fields=True
)

# Load the input data using the field mappings
# Location fields are included automatically because
# of the field mappings.
service_area.load(
    arcpy.nax.ServiceAreaInputDataType.Facilities,
    input_facilities,
    field_mappings
)

# Solve the analysis
result = service_area.solve()
print(result.solveSucceeded)

# ...analysis of the results continues...

Environments

Current Workspace