Select Layer By Location (Data Management)

Summary

Selects features based on a spatial relationship to features in another dataset.

Each feature in the Input Features parameter is evaluated against the features in the Selecting Features parameter. If the specified Relationship parameter is met, the input feature is selected.

Learn more about Select By Location including image examples of relationships

Usage

  • If the input is a feature class or dataset path, this tool will automatically create and return a new layer with the result of the tool applied.

  • The coordinate system in which the spatial relationship is evaluated can affect the result. Features that intersect in one coordinate system may not intersect in another.

    • This tool evaluates a spatial relationship in the coordinate system of the Input Features data source. Set the Output Coordinate System environment to Current Map [Layers] to use the same coordinate system as the current display.

  • This tool can be used to select features based on their spatial relationships to other features in the same layer. For examples, see Select based on spatial relationship within the layer.

  • The number of selected records will be listed in the geoprocessing history under Parameters > Count. Additionally, the Get Count tool can be used to count the number of selected records. From Python, the number of selected records can also be accessed from the tool's Result object.

  • For more information about using the three-dimensional spatial relationships Intersect 3D and Within a distance 3D (INTERSECT_3D and WITHIN_A_DISTANCE_3D in Python), see Select By Location: 3D relationships.

  • The Intersect (DBMS) spatial relationship (INTERSECT_DBMS in Python) may provide better performance than the Intersect relationship (INTERSECT in Python) when using enterprise geodatabase data; however, it is only supported under specific conditions. If all conditions are met, the spatial operation will be performed in the enterprise geodatabase database management system (DBMS) rather than on the client. Consider the following when using this spatial relationship:

    • The following requirements are necessary for the operation to run in the DBMS:
      • The Input Features and Selecting Features parameter values are from the same enterprise geodatabase workspace and must have the same spatial reference and geometry storage type.
      • The underlying DBMS is IBM Db2, Oracle, PostgreSQL, SAP HANA, or Microsoft SQL Server.
      • Supported geometry storage types for this option are ST_GEOMETRY (Db2, Oracle, PostgreSQL, and SAP HANA), PostGIS (PostgreSQL), SDO_GEOMETRY (Oracle), and MSSQLGeometry and MSSQLGeography (SQL Server). See Geodatabase management for information on installing and configuring your DBMS as well as information on configuring the geometry storage type of your choice so it will be available for use.
      • If you are using Oracle ST_GEOMETRY, you must configure the Oracle extproc to access ST_Geometry. See Configure the extproc to access ST_Geometry in Oracle for more information.
      • The Search Distance parameter is not set.
      • The Selection Type parameter value is New selection.
      • Existing selections prior to running the tool were made using a layer definition query, not a selection set.
    • The spatial operation is performed without applying an x,y tolerance during processing. Using an x,y tolerance is not supported in the DBMS. This may result in slightly different selections being returned compared to when the analysis is performed on the client with an x,y tolerance applied. See Feature class basics for more information on how an x,y tolerance is applied during client-side operations
    • Enterprise geodatabases in Db2, Oracle, PostgreSQL, SAP HANA, and SQL Server are supported. Each has their own geometry storage type that is supported by this relationship. See the vendor documentation specific to your DBMS to determine what to expect for each geometry storage type. There may be storage limitations that will impact performance and scalability when running spatial operations.

Syntax

arcpy.management.SelectLayerByLocation(in_layer, {overlap_type}, {select_features}, {search_distance}, {selection_type}, {invert_spatial_relationship})
ParameterExplanationData Type
in_layer
[in_layer,...]

The features that will be evaluated against the select_features parameter values. The selection will be applied to these features.

Feature Layer; Raster Layer; Mosaic Layer
overlap_type
(Optional)

Specifies the spatial relationship to be evaluated.

  • INTERSECTThe features in the input layer will be selected if they intersect a selecting feature. This is the default.
  • INTERSECT_3DThe features in the input layer will be selected if they intersect a selecting feature in three-dimensional space (x, y, and z).
  • INTERSECT_DBMSThe features in the input layer will be selected if they intersect a selecting feature. This option applies to enterprise geodatabases only. The selection will be processed in the enterprise geodatabase DBMS rather than on the client when all requirements are met (see usage notes). This option may provide better performance than performing the selection on the client.
  • WITHIN_A_DISTANCEThe features in the input layer will be selected if they are within the specified distance (using Euclidean distance) of a selecting feature. Use the search_distance parameter to specify the distance.
  • WITHIN_A_DISTANCE_3DThe features in the input layer will be selected if they are within a specified distance of a selecting feature in three-dimensional space. Use the search_distance parameter to specify the distance.
  • WITHIN_A_DISTANCE_GEODESICThe features in the input layer will be selected if they are within a specified distance of a selecting feature. Distance between features will be calculated using a geodesic formula that takes into account the curvature of the spheroid and correctly handles data near and across the dateline and poles. Use the search_distance parameter to specify the distance.
  • CONTAINSThe features in the input layer will be selected if they contain a selecting feature.
  • COMPLETELY_CONTAINSThe features in the input layer will be selected if they completely contain a selecting feature.
  • CONTAINS_CLEMENTINIThis spatial relationship yields the same results as COMPLETELY_CONTAINS with the exception that if the selecting feature is entirely on the boundary of the input feature (no part is properly inside or outside), the feature will not be selected. CLEMENTINI defines the boundary polygon as the line separating inside and outside, the boundary of a line is defined as its end points, and the boundary of a point is always empty.
  • WITHINThe features in the input layer will be selected if they are within a selecting feature.
  • COMPLETELY_WITHINThe features in the input layer will be selected if they are completely within or contained by a selecting feature.
  • WITHIN_CLEMENTINIThe result will be identical to WITHIN with the exception that if the entirety of the feature in the input layer is on the boundary of the feature in the selecting layer, the feature will not be selected. CLEMENTINI defines the boundary polygon as the line separating inside and outside, the boundary of a line is defined as its end points, and the boundary of a point is always empty.
  • ARE_IDENTICAL_TOThe features in the input layer will be selected if they are identical (in geometry) to a selecting feature.
  • BOUNDARY_TOUCHESThe features in the input layer will be selected if they have a boundary that touches a selecting feature. When the input features are lines or polygons, the boundary of the input feature can only touch the boundary of the selecting feature, and no part of the input feature can cross the boundary of the selecting feature.
  • SHARE_A_LINE_SEGMENT_WITHThe features in the input layer will be selected if they share a line segment with a selecting feature. The input and selecting features must be line or polygon.
  • CROSSED_BY_THE_OUTLINE_OFThe features in the input layer will be selected if they are crossed by the outline of a selecting feature. The input and selecting features must be lines or polygons. If polygons are used for the input or selecting layer, the polygon's boundary (line) will be used. Lines that cross at a point will be selected; lines that share a line segment will not be selected.
  • HAVE_THEIR_CENTER_INThe features in the input layer will be selected if their center falls within a selecting feature. The center of the feature is calculated as follows: for polygon and multipoint, the geometry's centroid is used; for line input, the geometry's midpoint is used.
String
select_features
(Optional)

The features in the Input Features parameter will be selected based on their relationship to the features from this layer or feature class.

Feature Layer
search_distance
(Optional)

The specified distance that will be searched. This parameter is only valid if the overlap_type parameter is set to WITHIN_A_DISTANCE, WITHIN_A_DISTANCE_GEODESIC, WITHIN_A_DISTANCE_3D, INTERSECT, INTERSECT_3D, HAVE_THEIR_CENTER_IN, or CONTAINS.

If the WITHIN_A_DISTANCE_GEODESIC option is selected, use a linear unit such as kilometers or miles.

Linear Unit
selection_type
(Optional)

Specifies how the selection will be applied to the input and how it will be combined with an existing selection. This tool does not include an option to clear an existing selection; use the CLEAR_SELECTION option on the Select Layer By Attribute tool.

  • NEW_SELECTIONThe resulting selection replaces any existing selection. This is the default.
  • ADD_TO_SELECTIONThe resulting selection is added to an existing selection. If no selection exists, this is the same as the NEW_SELECTION option.
  • REMOVE_FROM_SELECTIONThe resulting selection is removed from an existing selection. If no selection exists, the operation will have no effect.
  • SUBSET_SELECTIONThe resulting selection is combined with the existing selection. Only records that are common to both remain selected.
  • SWITCH_SELECTIONThe selection is switched. All records that were selected are removed from the selection, and all records that were not selected are added to the selection. The select_features and overlap_type parameters are ignored when this option is selected.
String
invert_spatial_relationship
(Optional)

Specifies whether the spatial relationship evaluation result will be used or the opposite result will be used. For example, this parameter can be used to get a list of features that do not intersect or are not within a given distance of features in another dataset.

  • NOT_INVERTThe query result will be used. This is the default.
  • INVERTThe opposite of the query result will be used. If the selection_type parameter is used, the reversal of the selection occurs before it is combined with existing selections.
Boolean

Derived Output

NameExplanationData Type
out_layer_or_view

The updated inputs with selections applied.

Feature Layer; Mosaic Layer
out_layers_or_views

The names of the updated inputs.

Feature Layer; Mosaic Layer
count

The number of selected records.

Long

Code sample

SelectLayerByLocation example 1 (Python window)

The following Python window script demonstrates how to use the SelectLayerByLocation function in immediate mode.

import arcpy
arcpy.SelectLayerByLocation_management("parcel_lyr", "have_their_center_in", 
                                       "c:/kamsack.gdb/city_limits")
SelectLayerByLocation example 2 (stand-alone script)

The following stand-alone script shows how to use the SelectLayerByLocation function in a workflow to extract features to a new feature class based on location and an attribute query.

# Description: Extract features to a new feature class based on a 
#              location and an attribute query

# Import arcpy and set path to data
import arcpy
arcpy.env.workspace = "c:/data/mexico.gdb"

# Make a layer and select cities that overlap the chihuahua polygon
chihuahua_cities = arcpy.SelectLayerByLocation_management('cities', 'INTERSECT', 
                                                          'chihuahua')

# From the previous selection, select a subset of cities that have 
# population > 10,000
arcpy.SelectLayerByAttribute_management(chihuahua_cities, 
                                        'SUBSET_SELECTION', 
                                        '"population" > 10000')

# If features matched criteria, write them to a new feature class
matchcount = int(arcpy.GetCount_management(chihuahua_cities)[0]) 

if matchcount == 0:
    print('no features matched spatial and attribute criteria')
else:
    arcpy.CopyFeatures_management(chihuahua_cities, 'chihuahua_10000plus')
    print('{0} cities that matched criteria written to {0}'.format(
        matchcount, chihuahua_10000plus))
SelectLayerByLocation example 3 (stand-alone script)

The following stand-alone script shows a variety of uses of the overlap_type parameter's WITHIN_A_DISTANCE and WITHIN_A_DISTANCE_GEODESIC options with the search_distance parameter.

# Description: Select features within a distance

# Import arcpy and set path to data
import arcpy

arcpy.env.workspace = r"c:\data\mexico.gdb"

arcpy.SelectLayerByLocation_management('cities', 'WITHIN_A_DISTANCE', 
                                       'chihuahua', '1.5 Miles')
arcpy.SelectLayerByLocation_management('cities', 'WITHIN_A_DISTANCE_GEODESIC', 
                                       'chihuahua', '200 Kilometers')

# When using WITHIN_A_DISTANCE, if distance units are not specified, the 
# distance value is assumed to be in the units of the input dataset's coordinate 
# system
arcpy.SelectLayerByLocation_management('cities', 'WITHIN_A_DISTANCE', 
                                       'chihuahua', '200')

# When using WITHIN_A_DISTANCE_GEODESIC, if distance units are not specified, 
# the distance value is assumed to be in meters
arcpy.SelectLayerByLocation_management('cities', 'WITHIN_A_DISTANCE_GEODESIC', 
                                       'chihuahua', '200')

Licensing information

  • Basic: Yes
  • Standard: Yes
  • Advanced: Yes

Related topics