Calculate Locations (Network Analyst)—ArcGIS Pro

Summary

Locates input features on a network and adds fields describing these network locations to the input features. The tool is used to store the network location information as feature attributes to quickly load the features as inputs for a network analysis.

Learn more about locating features on a network

Usage

This tool is used to calculate locations fields that can be input to the Add Locations tool. It should be used on features that will be used more than once as input to a network analysis layer. Once the locations have been computed, the Use Network Location Fields instead of geometry parameter on the Add Locations tool can be used to quickly load the features as network locations.
This tool can also be used to recalculate the network locations that are unlocated in your network analysis layer using a different set of search options. For example, If the stops in your route network analysis layer were initially added with a search tolerance of 500 meters and few of your stops were unlocated, you can select the unlocated stops, for example, using the Select Layer By Attribute tool, and rerun this tool specifying the stops sublayer as the Input features parameter value with an increased search tolerance.
This tool runs significantly faster if the feature classes used as the network sources in the network dataset have a valid and up-to-date spatial index.

Parameters

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 (specified in the Location Ranges Field parameter), only geodatabase feature classes are supported.	Table View
Input Analysis Network	The network dataset that will be used to calculate the locations. If a sublayer of a network analysis layer is used as input features, the parameter is automatically set to the network dataset referenced by the network analysis layer.	Network Dataset Layer
Search Tolerance (Optional)	The search tolerance that will be used to locate the input features on the network. Features that are outside the search tolerance are left unlocated. The parameter includes a value and units for the tolerance. The default is 5000 meters. The parameter is not used when calculating locations for line or polygon features.	Linear Unit
Search Criteria (Optional)	The sources in the network dataset that will be searched when calculating network locations and the portions of geometry (also known as snap types) that will be used. For example, if the network dataset references separate feature classes representing streets and sidewalks, you can choose to locate inputs on streets but not on sidewalks. The following are the available snap type choices for each network source: SHAPE—The point will locate on the closest point of an element in this network source. MIDDLE—The point will locate on the closest midpoint of an element in this network source. END—The point will locate on the closest endpoint of an element in this network source. NONE—The point will not locate on elements in this network source. The MIDDLE and END options are maintained for backward compatibility. Use the SHAPE option to locate your inputs on a particular network source; otherwise, use NONE. When calculating locations for line or polygon features, only the SHAPE snap type is used, even if other snap types are specified. The default value is SHAPE for all network sources except override junctions created by running the Dissolve Network tool and system junctions, which have a default of NONE. This parameter is not used when the network data source is a portal service.	Value Table
Find Closest among All Classes (Optional)	Note: This parameter is only available via Python.	Boolean
Source ID Field (Optional)	The name of the field to be created or updated with the source ID of the computed network location. A field named SourceID will be created or updated by default.	Field
Source OID Field (Optional)	The name of the field to be created or updated with the source OID of the computed network location. A field named SourceOID will be created or updated by default.	Field
Percent Along Field (Optional)	The name of the field to be created or updated with the percent along with the computed network location. A field named PosAlong will be created or updated by default.	Field
Side of Edge Field (Optional)	The name of the field to be created or updated with the side of edge on which the point feature is located on the computed network location. A field named SideOfEdge will be created or updated by default.	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. A field named SnapX will be created or updated by default.	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. A field named SnapY will be created or updated by default.	Field
Distance from Feature Field (Optional)	The name of the field to be created or updated with the distance of the point feature from the computed network location. A field named Distance is created or updated by default. The output field is in meters.	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. A field named SnapZ will be created or updated by default.	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 the line or polygon features. A field named Locations will be created or updated by default.	Field
Exclude Restricted Portions of the Network (Optional)	Note: This parameter is only available via Python.	Boolean
Search Query (Optional)	Defines a query that will restrict the search to a subset of the features in a source feature class. This is useful if you don't want to locate on features that may be unsuitable for your analysis. For example, you can use the query to exclude all features with a particular road class. A separate SQL expression can be specified per source feature class of the network dataset. By default, no query is used for any source. This parameter is not used when the network data source is a portal service. The SQL expression for a given network source is specified by selecting the source name in the Name column and using the SQL expression builder in the Query column. For more information on SQL syntax, see SQL reference for query expressions used in ArcGIS. Any network source not explicitly specified in the tool dialog box will have no query applied.	Value Table
Travel Mode (Optional)	The name of the travel mode to be used in the analysis. If you select a travel mode, the travel mode settings, such as restrictions and impedance attributes, will be considered when calculating location fields. For example, if the closest network edge to one of your input points is forbidden to trucks and your travel mode is set for trucking, Calculate Locations will locate the point on the next-closest network edge that is not forbidden for trucks. 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, the travel mode parameter must be set to the network analysis layer's travel mode.	String

Derived Output

Label	Explanation	Data Type
Updated Input Features	The updated input features.	Table View

arcpy.na.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 (specified in the Location Ranges Field parameter), only geodatabase feature classes are supported.	Table View
in_network_dataset	The network dataset that will be used to calculate the locations. If a sublayer of a network analysis layer is used as input features, the parameter must be set to the network dataset referenced by the network analysis layer.	Network Dataset Layer
search_tolerance (Optional)	The search tolerance that will be used to locate the input features on the network. Features that are outside the search tolerance are left unlocated. The parameter includes a value and units for the tolerance. The default is 5000 meters. The parameter is not used when calculating locations for line or polygon features.	Linear Unit
search_criteria [[Source, SnapType],...] (Optional)	The sources in the network dataset that will be searched when calculating network locations and the portions of geometry (also known as snap types) that will be used. For example, if the network dataset references separate feature classes representing streets and sidewalks, you can choose to locate inputs on streets but not on sidewalks. The following are the available snap type choices for each network source: SHAPE—The point will locate on the closest point of an element in this network source. MIDDLE—The point will locate on the closest midpoint of an element in this network source. END—The point will locate on the closest endpoint of an element in this network source. NONE—The point will not locate on elements in this network source. The MIDDLE and END options are maintained for backward compatibility. Use the SHAPE option to locate your inputs on a particular network source; otherwise, use NONE. When calculating locations for line or polygon features, only the SHAPE snap type is used, even if other snap types are specified. The default value is SHAPE for all network sources except override junctions created by running the Dissolve Network tool and system junctions, which have a default of NONE. This parameter is not used when the network data source is a portal service. 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. 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 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. For geodatabase network datasets, the snap types can be specified for each subtype of the network source. For example, if the network has a source called Streets, and that source has a subtype called Local Streets, specify the snap type for local streets using ["Streets : Local Streets", "SHAPE"].	Value Table
match_type (Optional)	Specifies how new network locations will be matched to network sources. MATCH_TO_CLOSEST —The new network locations will be matched to the closest network source among all the sources that have a snap type specified in the search criteria. This is the default. PRIORITY —The new network locations will be matched to the first network source having a snap type specified in the search criteria. The sources are searched in the priority order, and the searching stops when the location is found within the search tolerance. The parameter is not used when calculating locations for line or polygon features.	Boolean
source_ID_field (Optional)	The name of the field to be created or updated with the source ID of the computed network location. A field named SourceID will be created or updated by default. The parameter is not used when calculating locations for line or polygon features.	Field
source_OID_field (Optional)	The name of the field to be created or updated with the source OID of the computed network location. A field named SourceOID will be created or updated by default. The parameter is not used when calculating locations for line or polygon features.	Field
position_field (Optional)	The name of the field to be created or updated with the percent along with the computed network location. A field named PosAlong will be created or updated by default. The parameter is not used when calculating locations for line or polygon features.	Field
side_field (Optional)	The name of the field to be created or updated with the side of edge on which the point feature is located on the computed network location. A field named SideOfEdge will be created or updated by default. The parameter is not used when calculating locations for line or polygon features.	Field
snap_X_field (Optional)	The name of the field to be created or updated with the x-coordinate of the computed network location. A field named SnapX will be created or updated by default. The parameter is not used when calculating locations for line or polygon features.	Field
snap_Y_field (Optional)	The name of the field to be created or updated with the y-coordinate of the computed network location. A field named SnapY will be created or updated by default. The parameter is not used when calculating locations for line or polygon features.	Field
distance_field (Optional)	The name of the field to be created or updated with the distance of the point feature from the computed network location. A field named Distance is created or updated by default. The output field is in meters. The parameter is not used when calculating locations for line or polygon features.	Field
snap_Z_field (Optional)	The name of the field to be created or updated with the z-coordinate of the computed network location. A field named SnapZ will be created or updated by default. The parameter is not used when calculating locations for line or polygon features. When calculating locations for point features, the parameter is used only when the input network dataset supports connectivity based on z-coordinate values of the network sources. In all other cases, use "#" as the parameter value.	Field
location_field (Optional)	The name of the field to be created or updated with the location ranges of the computed network locations for the line or polygon features. A field named Locations will be created or updated by default. The parameter is used only when the calculating locations for line or polygon features. For input point features, use "#" as the parameter value.	Field
exclude_restricted_elements (Optional)	Specifies whether restricted portions of the network are excluded when locating inputs. Points will not be located on elements that are restricted in the specified travel mode. If no travel mode is specified, restrictions in the network's default travel mode are used. EXCLUDE —The network locations are only placed on traversable portions of the network. This prevents placing network locations on elements that you can't reach due to restrictions or barriers. Before relocating your network locations using this option, ensure that you have added all the restriction barriers to the network analysis layer to get expected results. This is the default. INCLUDE —The network locations are placed on all the elements of the network. The network locations that are relocated with this option may be unreachable during the solve process if they are placed on restricted elements.	Boolean
search_query [[Source, Expression],...] (Optional)	Defines a query that will restrict the search to a subset of the features in a source feature class. This is useful if you don't want to locate on features that may be unsuitable for your analysis. For example, you can use the query to exclude all features with a particular road class. A separate SQL expression can be specified per source feature class of the network dataset. By default, no query is used for any source. This parameter is not used when the network data source is a portal service. The parameter value is specified as a list of nested lists. The nested lists are composed of two values indicating the name and the SQL expression for all of the network sources. For more information on SQL syntax, see SQL reference for query expressions used in ArcGIS. Any network source not included in this list will have no query applied. Similarly, an expression specified as an empty string will also be interpreted as no query. For example, the parameter value [["Streets", "\"CFCC\" = 'A15'"], ["Streets_ND_Junctions", ""]] specifies a query for the Streets source feature class to only locate inputs on streets where the CFCC field has a value of A15. No query is applied to the Streets_ND_Junctions source feature class.	Value Table
travel_mode (Optional)	The name of the travel mode to be used in the analysis. If you select a travel mode, the travel mode settings, such as restrictions and impedance attributes, will be considered when calculating location fields. For example, if the closest network edge to one of your input points is forbidden to trucks and your travel mode is set for trucking, Calculate Locations will locate the point on the next-closest network edge that is not forbidden for trucks. The available travel modes depend on the in_network_dataset parameter value. If a sublayer of a network analysis layer is used as input features, the travel mode parameter must be set to the network analysis layer's travel mode.	String

Derived Output

Name	Explanation	Data Type
out_point_feature_class	The updated input features.	Table View

Code sample

CalculateLocations example 1 (Python window)

Calculate locations for point features using only the required parameters.

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 (Python window)

Calculate locations for point features on street features, excluding other network sources.

warehouses = "C:/Data/Paris.gdb/Analysis/Warehouses"
network = "C:/Data/Paris.gdb/Transportation/ParisMultimodal_ND"
arcpy.na.CalculateLocations(warehouses, network, "5000 Meters",
    [["Metro_Lines", "NONE"], ["Streets", "SHAPE"],
    ["Transfer_Stations", "NONE"], ["Metro_Entrances", "NONE"],
    ["Metro_Stations", "NONE"], ["ParisMultimodal_ND_Junctions", "NONE"]],
    "MATCH_TO_CLOSEST", "SID", "SOID", "PA", "SOE", "SnapX", "SnapY",
    "Distance")

CalculateLocations example 3 (Python window)

Calculate locations for polygon features

parks = "C:/Data/SanFrancisco.gdb/Analysis/Hospitals/Basemap/Parks"
network = "C:/Data/SanFrancisco.gdb/Transportation/Streets_ND"
arcpy.na.CalculateLocations(parks, network, "", [["Streets", "SHAPE"],
                            ["Streets_ND_Junctions", "NONE"]],
                            location_field="Locations")

CalculateLocations example 4 (stand-alone script)

The following Python script demonstrates how to use the CalculateLocations tool in a stand-alone script.

# Name: CalculateLocations_ex04.py
# Description: Calculate network locations for fire stations. Make sure that the
#              fire stations are not located on the freeways.
# Requirements: Network Analyst Extension

#Import system modules
import arcpy
from arcpy import env

try:
    #Set environment settings
    env.workspace = "C:/Data/SanFrancisco.gdb"

    #Set local variables
    in_features = "Analysis/FireStations"
    network = "Transportation/Streets_ND"
    search_tolerance = "2000 Meters"
    search_criteria = [["Streets", "SHAPE"], ["Streets_ND_Junctions", "NONE"]]
    search_query = [["Streets", '"FREEWAY" = 0'], ["Streets_ND_Junctions", ""]]

    #Calculate network locations and store them in defaut field names
    arcpy.na.CalculateLocations(in_features, network, search_tolerance,
                                search_criteria, "MATCH_TO_CLOSEST",
                                exclude_restricted_elements="EXCLUDE",
                                search_query=search_query)

    print("Script completed successfully.")

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

Environments

Current Workspace

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes

Summary

Usage

Parameters

Note:

Note:

Derived Output

Derived Output

Code sample

Environments

Licensing information

Related topics

In this topic