Desktop Help 10.0 - Calculate Locations (Network Analyst)

Summary

Adds fields to the input features that contain the network location of the 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 layer.

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, then 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 re-calculate 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 re-run this tool specifying the stops sub layer 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_na (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})

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 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	The search tolerance for locating 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 parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Linear unit
search_criteria [[Source, SnapType],...]	Specifies which sources in the network dataset will be searched when finding locations and what portions of geometry (also known as snap types) will be used. The parameter value is specified as a list with nested lists. The nested list is made up 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" keywords. For example, when finding locations, the parameter value [["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. To specify multiple snap types for a single network source, use the combination of the snap type keywords separate 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. When calculating locations for line or polygon features, only the Shape snap type is used even if other snap types are specified.	Value Table
match_type (Optional)	MATCH_TO_CLOSEST —Matches the new network locations to the closest network source among all the sources that have a snap type specified in the search criteria . This is the default. PRIORITY —Matches the new network locations 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. In such cases, use "#" as the parameter value.	Boolean
source_ID_field (Optional)	Name of the field to be created or updated with the source ID of the computed network location. A field called "SourceID" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
source_OID_field (Optional)	Name of the field to be created or updated with the source OID of the computed network location. A field called "SourceOID" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
position_field (Optional)	Name of the field to be created or updated with the percent along of the computed network location. A field called "PosAlong" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
side_field (Optional)	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 called "SideOfEdge" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
snap_x_field (Optional)	Name of the field to be created or updated with the x-coordinate of the computed network location. A field called "SnapX" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
snap_y_field (Optional)	Name of the field to be created or updated with the y-coordinate of the computed network location. A field called "SnapY" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
distance_field (Optional)	Name of the field to be created or updated with the distance of the point feature from the computed network location. A field called "Distance" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value.	Field
snap_Z_field (Optional)	Name of the field to be created or updated with the z-coordinate of the computed network location. A field called "SnapZ" is created or updated by default. The parameter is not used when calculating locations for line or polygon features. In such cases, use "#" as the parameter value. 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)	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 called "Locations" is 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)	This parameter is applicable only when the input features are from the sub layer of a network analysis layer and are not barrier objects. In all other cases, use "#" as the parameter value. EXCLUDE —Specifies that 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, make sure that you have already added all the restriction barriers to the network analysis layer to get expected results. INCLUDE —Specifies that 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)	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 made up 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 ArcSDE geodatabases, shapefiles, or SDC, enclose field names in double quotes: "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 a SQL expression for the Streets source feature class and no expression for Streets_ND_Junctions source feature class. Note that the double quotes used to enclose the field name CFCC are escaped using back slash characters to avoid a parsing error from the Python interpreter.	Value Table

Code Sample

CalculateLocations example 1 (Python window)

Calculate Locations for point features using only the required parameters.

import arcpy
arcpy.env.workspace = "C:/ArcTutor/Network Analyst/Tutorial/SanFrancisco.gdb"
arcpy.CalculateLocations_na("Analysis/Stores","Transportation/Streets_ND",
                            "5000 Meters",[["Streets","SHAPE"],
                                           ["Streets_ND_Junctions","NONE"]])

CalculateLocations example 2 (Python window)

Calculate Locations for point features on a subtype of a network source.

import arcpy
arcpy.env.workspace = "C:/ArcTutor/Network Analyst/Tutorial/Paris.gdb"
arcpy.CalculateLocations_na(
    "Analysis/Warehouses","Transportation/ParisNet","5000 Meters",
    [["Streets : Highways","NONE"],["Streets : Major Roads","NONE"],
     ["Streets : Local Streets","SHAPE"],["ParisNet_Junctions", "NONE"]],
    "MATCH_TO_CLOSEST","SID","SOID","PA","SOE","SnapX","SnapY","Distance",
    "","","","")

CalculateLocations example 3 (Python window)

Calculate Locations for polygon features

import arcpy
arcpy.env.workspace = "C:/ArcTutor/Network Analyst/Tutorial/SanFrancisco.gdb"
arcpy.CalculateLocations_na("Basemap/Parks","Transportation/Streets_ND","",
                            [["Streets","SHAPE"],
                             ["Streets_ND_Junctions","NONE"]],
                            location_field="Locations")

CalculateLocations example 4 (Stand-alone Python 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 
# Author: ESRI

#Import system modules
import arcpy
from arcpy import env


#Check out the Network Analyst extension license
arcpy.CheckOutExtension("Network")

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

#Set local variables
inFeatures = "Analysis/FireStations"
inNetworkDataset = "Transportation/Streets_ND"
searchTolerance = "2000 Meters"
searchCriteria = [["Streets","SHAPE"],["Streets_ND_Junctions","NONE"]]
searchQuery = [["Streets",'"FREEWAY" = 0'],["Streets_ND_Junctions",""]]

#Calculate network locations and store them in defaut field names
arcpy.CalculateLocations_na(inFeatures,inNetworkDataset,searchTolerance,
                            searchCriteria,"MATCH_TO_CLOSEST", 
                            exclude_restricted_elements="EXCLUDE",
                            search_query=searchQuery)
print "Script completed successfully."

Environments

Current Workspace

Licensing Information

ArcView: Requires Network Analyst

ArcEditor: Requires Network Analyst

ArcInfo: Requires Network Analyst

Published 6/7/2010