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.
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 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.
Syntax
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})| Parameter | 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 finding locations and the portions of geometry (also known as snap types) that will be used. The parameter value is specified as a list with nested lists. The nested list is composed of two values indicating the name and the snap type for each network source. The snap type is specified using the SHAPE, MIDDLE, END, or NONE keyword.
To specify multiple snap types for a single network source, use the combination of the snap type keywords separated by an underscore. For example, MIDDLE_END specifies that the locations can be snapped to the middle or end of the network source. For geodatabase network datasets, the snap types can be specified for each subtype of the network source (["Streets : Local Streets","SHAPE"]). When calculating locations for line or polygon features, only the SHAPE snap type is used, even if other snap types are specified. Any network source not included in this list will use its default snap type. It is safest to include all network sources in your list and explicitly set the snap type for each. The default value is SHAPE for all network sources except system junctions, which has a default of NONE. | Value Table |
match_type (Optional) |
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.
| 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 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. | Value Table |
travel_mode (Optional) | Name of the travel mode which will 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 | Updated input features. | Table View |
Code sample
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"]])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")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")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
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes