Add Locations (Network Analyst)

Summary

Adds input features or records to a network analysis layer. The inputs are added to specific sublayers such as stops and barriers. When the network analysis layer references a network dataset as its network data source, the tool calculates the network locations of the inputs, unless precalculated network location fields are mapped from the inputs.

Learn more about how the Add Locations tool locates analysis inputs on the network

Usage

• When locating inputs, the network analysis layer's travel mode and existing barriers are considered. Consequently, it is recommended that you set the travel mode for the analysis and load barriers before loading other analysis inputs.

• The Search Tolerance, Search Criteria, and Search Query parameter values 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 you change the value of the Search Tolerance, Search Criteria, or Search Query parameter, 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 obeys the same location settings you used when initially calculating network locations.

• If the analysis layer references a portal service, the location fields are not calculated until you solve the analysis. For these layers, the Add Locations tool appends the inputs to the analysis layer without calculating location fields. Consequently, some tool parameters do not apply to these layers and are hidden in the Geoprocessing pane and ignored in Python.

Parameters

Dialog

Label	Explanation	Data Type
Input Network Analysis Layer	The network analysis layer to which the network analysis objects will be added.	Network Analyst Layer
Sub Layer	The name of the sublayer of the network analysis layer to which the network analysis objects will be added.	String
Input Locations	The feature class or table containing the locations to be added to the network analysis sublayer.	Table View
Field Mappings (Optional)	The mapping between the input fields of the network analysis sublayer to which locations will be added and the fields in the input data or specified constants. Input sublayers of network analysis layers have a set of input fields that can be populated to modify or control analysis behavior. When adding locations to the sublayer, you can use this parameter to map field values from the input table to these fields in the sublayer. You can also use field mappings to specify a constant default value for each property. If neither the Field value nor the Default value is specified for a property, the resulting network analysis objects will have null values for that property. A complete list of input fields for each sublayer for each network analysis layer type is available in the documentation for each layer. For example, examine the Route layer's Stops sublayer's input fields. If the data being loaded contains precalculated network locations or location ranges based on the network data source and travel mode used for the analysis, choose the Use Network Location Fields option from the drop-down menu. Adding the network analysis objects using the network location fields is quicker than loading by geometry. Learn more about network location fields Note: ArcGIS Online and some ArcGIS Enterprise portals do not support using network location fields. For network analysis layers that use one of these portals as the network data source, all inputs will be located at solve time, and any mapped location fields will be ignored.	Network Analyst Class FieldMap
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 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 adding locations to sublayers with line or polygon geometry, such as Line Barriers and Polygon Barriers. This parameter is not used when adding locations using existing network location fields. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	Linear Unit
Sort Field (Optional)	The field on which the network analysis objects will be sorted as they are added to the network analysis layer. The default is the ObjectID field in the input feature class or table.	Field
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 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. This parameter is not used when adding locations using existing network location fields. This parameter is not used when the network analysis layer's network data source is ArcGIS Online. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	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
Append to Existing Locations (Optional)	Specifies whether new network analysis objects will be appended to existing objects. Checked—The new network analysis objects will be appended to the existing set of objects in the selected sublayer. This is the default. Unchecked—The existing network analysis objects will be deleted and replaced with the new objects.	Boolean
Snap to Network (Optional)	Specifies whether the inputs will be snapped to their calculated network locations or represented at their original geographic location. To use curb approach in the analysis to control which side of the road a vehicle must use to approach a location, do not snap the inputs to their network locations, or use a snap offset to ensure that the point remains clearly to one side of the road. The parameter is not used when adding locations to sublayers with line or polygon geometry, such as Line Barriers and Polygon Barriers. This parameter is not used when the input network analysis layer's network data source is a portal service. Checked—The geometries of the network locations will be snapped to their network locations. Unchecked—The geometries of the network locations will be based on the geometries of the input features. This is the default.	Boolean
Snap Offset (Optional)	An offset distance that will be applied when snapping a point to the network. An offset distance of zero means the point will be coincident with the network feature (typically a line). To offset the point from the network feature, enter an offset distance. The offset is in relation to the original point location; that is, if the original point was on the left side, its new location will be offset to the left. If it was originally on the right side, its new location will be offset to the right. The default is 5 meters. However, this parameter is ignored if Snap to Network is unchecked. The parameter is not used when adding locations to sublayers with line or polygon geometry, such as Line Barriers and Polygon Barriers. This parameter is not used when the input network analysis layer's network data source is a portal service.	Linear Unit
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. 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. This parameter is not used when adding locations using existing network location fields. This parameter is not used when the network analysis layer's network data source is ArcGIS Online. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	Value Table
Allow automatic relocating at solve time (Optional)	Specifies whether inputs with existing network location fields can be automatically relocated at solve time to ensure valid, routable location fields for the analysis. Checked—Points located on restricted network elements and points affected by barriers will be relocated at solve time to the closest routable location. This is the default. Unchecked—Network location fields will be used at solve time as is, even if the points are unreachable, and this may cause the solve to fail. 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. Even if the automatic relocating at solve time is not allowed, inputs with no location fields or incomplete location fields will be located at solve time. This parameter is not used when the network analysis layer's network data source is ArcGIS Online. This parameter is not used when the network analysis layer's network data source is an ArcGIS Enterprise portal that does not support using network location fields. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	Boolean

Derived Output

Label	Explanation	Data Type
Updated Input Network Analysis Layer	The updated network analysis layer.	Network Analyst Layer

Python

arcpy.management.AddLocations(in_network_analysis_layer, sub_layer, in_table, {field_mappings}, {search_tolerance}, {sort_field}, {search_criteria}, {match_type}, {append}, {snap_to_position_along_network}, {snap_offset}, {exclude_restricted_elements}, {search_query}, {allow_auto_relocate})

Name	Explanation	Data Type
in_network_analysis_layer	The network analysis layer to which the network analysis objects will be added.	Network Analyst Layer
sub_layer	The name of the sublayer of the network analysis layer to which the network analysis objects will be added.	String
in_table	The feature class or table containing the locations to be added to the network analysis sublayer.	Table View
field_mappings (Optional)	The mapping between the input fields of the network analysis sublayer to which locations will be added and the fields in the input data or specified constants. Input sublayers of network analysis layers have a set of input fields that can be populated to modify or control analysis behavior. When adding locations to the sublayer, you can use this parameter to map field values from the input table to these fields in the sublayer. You can also use field mappings to specify a constant default value for each property. If neither the Field value nor the Default value is specified for a property, the resulting network analysis objects will have null values for that property. A complete list of input fields for each sublayer for each network analysis layer type is available in the documentation for each layer. For example, examine the Route layer's Stops sublayer's input fields. An NAClassFieldMappings object obtained from the NAClassFieldMappings class is used to specify the parameter value. The NAClassFieldMappings object is a collection of NAClassFieldMap objects that allow you to specify the default values or map a field name from the input features for the properties of the network analysis object. If the data being loaded contains network locations or location ranges based on the network dataset used for the analysis, map the network location fields from the input features to the network location properties. Specifying the network location fields in the field mappings is similar to using the Use Network Location Fields option on the tool dialog box. Learn more about network location fields Note: ArcGIS Online and some ArcGIS Enterprise portals do not support using network location fields. For network analysis layers that use one of these portals as the network data source, all inputs will be located at solve time, and any mapped location fields will be ignored.	Network Analyst Class FieldMap
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 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 adding locations to sublayers with line or polygon geometry, such as Line Barriers and Polygon Barriers. This parameter is not used when adding locations using existing network location fields. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	Linear Unit
sort_field (Optional)	The field on which the network analysis objects will be sorted as they are added to the network analysis layer. The default is the ObjectID field in the input feature class or table.	Field
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 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. This parameter is not used when adding locations using existing network location fields. This parameter is not used when the network analysis layer's network data source is ArcGIS Online. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	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
append (Optional)	Specifies whether new network analysis objects will be appended to existing objects. APPEND—The new network analysis objects will be appended to the existing set of objects in the selected sublayer. This is the default. CLEAR—The existing network analysis objects will be deleted and replaced with the new objects.	Boolean
snap_to_position_along_network (Optional)	Specifies whether the inputs will be snapped to their calculated network locations or represented at their original geographic location. To use curb approach in the analysis to control which side of the road a vehicle must use to approach a location, do not snap the inputs to their network locations, or use a snap offset to ensure that the point remains clearly to one side of the road. The parameter is not used when adding locations to sublayers with line or polygon geometry, such as Line Barriers and Polygon Barriers. This parameter is not used when the input network analysis layer's network data source is a portal service. NO_SNAP— The geometries of the network locations will be based on the geometries of the input features. This is the default. SNAP—The geometries of the network locations will be snapped to their network locations.	Boolean
snap_offset (Optional)	An offset distance that will be applied when snapping a point to the network. An offset distance of zero means the point will be coincident with the network feature (typically a line). To offset the point from the network feature, enter an offset distance. The offset is in relation to the original point location; that is, if the original point was on the left side, its new location will be offset to the left. If it was originally on the right side, its new location will be offset to the right. The default is 5 meters. However, this parameter is ignored if snap_to_position_along_network is set to NO_SNAP. The parameter is not used when adding locations to sublayers with line or polygon geometry, such as Line Barriers and Polygon Barriers. This parameter is not used when the input network analysis layer's network data source is a portal service.	Linear Unit
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. 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. This parameter is not used when adding locations using existing network location fields. This parameter is not used when the network analysis layer's network data source is ArcGIS Online. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	Value Table
allow_auto_relocate (Optional)	Specifies whether inputs with existing network location fields can be automatically relocated at solve time to ensure valid, routable location fields for the analysis. ALLOW— Points located on restricted network elements and points affected by barriers will be relocated at solve time to the closest routable location. This is the default. NO_ALLOW—Network location fields will be used at solve time as is, even if the points are unreachable, and this may cause the solve to fail. 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. Even if the automatic relocating at solve time is not allowed, inputs with no location fields or incomplete location fields will be located at solve time. This parameter is not used when the network analysis layer's network data source is ArcGIS Online. This parameter is not used when the network analysis layer's network data source is an ArcGIS Enterprise portal that does not support using network location fields. Legacy: This parameter is not used when the network analysis layer's network data source is a portal running a version of ArcGIS Enterprise earlier than 11.0.	Boolean

Derived Output

Name	Explanation	Data Type
output_layer	The updated network analysis layer.	Network Analyst Layer

Code sample

AddLocations example 1 (Python window)

Run the tool in the Python window to add stops to a route analysis layer named Route.

import arcpy
hospitals = "C:/Data/SanFrancisco.gdb/Analysis/Hospitals"
arcpy.na.AddLocations("Route", "Stops", hospitals)

AddLocations example 2 (workflow)

The following stand-alone Python script demonstrates how the AddLocations function can be used to load origins and destinations into an OD Cost Matrix layer.

Legacy:

The GetNASublayer function can be used to retrieve the sublayers of a network analysis layer. It was introduced in ArcGIS Pro 2.7. In earlier software versions, the best way to retrieve a sublayer object of a network analysis layer was to use the listLayers method of the network analysis Layer object using the sublayer name as a wildcard.

# Name: AddLocations_Workflow.py
# Description: Calculate a travel time matrix between stores. Use the Add
#               Locations tool to load origins and destinations into an OD Cost
#               Matrix layer. Since the origins and destinations are the same in
#               this case, the origins are first loaded from the stores feature
#               class using geometry, and the destinations are loaded from the
#               origins using network location fields in order to speed up the
#               load times.
# Requirements: Network Analyst Extension

# Import system modules
import arcpy
from arcpy import env
import os

try:
    # Check out Network Analyst license if available. Fail if the Network Analyst license is not available.
    if arcpy.CheckExtension("network") == "Available":
        arcpy.CheckOutExtension("network")
    else:
        raise arcpy.ExecuteError("Network Analyst Extension license is not available.")

    # Set environment settings
    output_dir = "C:/Data"
    # The NA layer's data will be saved to the workspace specified here
    env.workspace = os.path.join(output_dir, "Output.gdb")
    env.overwriteOutput = True

    # Set inputs and outputs
    input_gdb = "C:/Data/SanFrancisco.gdb"
    network = os.path.join(input_gdb, "Transportation", "Streets_ND")
    layer_name = "StoreTravelTimeMatrix"
    travel_mode = "Driving Time"
    stores = os.path.join(input_gdb, "Analysis", "Stores")
    search_tolerance = "500 Meters"
    search_query = [["Streets", '"FREEWAY" = 0'], ["Streets_ND_Junctions", ""]]
    output_layer_file = os.path.join(output_dir, layer_name + ".lyrx")

    # Create a new OD cost matrix analysis layer. For this scenario, the default
    # value for all the remaining parameters statisfies the analysis requirements
    result_object = arcpy.na.MakeODCostMatrixAnalysisLayer(
        network, layer_name, travel_mode
    )

    # Get the layer object from the result object. The OD cost matrix layer can
    # now be referenced using the layer object.
    layer_object = result_object.getOutput(0)

    # Get the names of all the sublayers within the OD layer.
    sublayer_names = arcpy.na.GetNAClassNames(layer_object)
    # Store the layer names for later use
    origins_layer_name = sublayer_names["Origins"]
    destinations_layer_name = sublayer_names["Destinations"]

    # Load store features as origins using the geometry of store features.
    # Ensure that the stores are not located on freeways by using a search query.
    arcpy.na.AddLocations(
        layer_object, origins_layer_name, stores, "",
        search_tolerance, search_query=search_query
    )

    # Because we want our origins and destinations to be the same, load the
    # origins as destinations using the network locations fields. Loading using
    # existing network location fields is much faster than loading using geometry
    # because the network locations have already been calculated.
    # Create a field mappings object that supports network location fields using
    # the candidate fields from origins
    origins_sublayer = arcpy.na.GetNASublayer(layer_object, "Origins")
    candidate_fields = arcpy.ListFields(origins_sublayer)
    field_mappings = arcpy.na.NAClassFieldMappings(
        layer_object, destinations_layer_name, True, candidate_fields
    )
    arcpy.na.AddLocations(
        layer_object, destinations_layer_name, origins_sublayer, field_mappings
    )

    # Solve the od cost matrix layer. Halt the execution if there is an
    # invalid location
    arcpy.na.Solve(layer_object, "HALT")

    # Save the solved OD cost matrix layer as a layer file on disk
    layer_object.saveACopy(output_layer_file)

    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