Add Spatial Join (Data Management)

Summary

Joins attributes from one feature to another based on the spatial relationship. The target features and the joined attributes from the join features will be joined.

See Select By Location graphic examples for more information.

Usage

• A spatial join matches rows from the Join Features values to the Target Features values based on their relative spatial locations.

• The tool creates the following fields:

  • Join_Count—The number of join features that match each target feature
  • TARGET_FID—The Object ID of the target feature

• This tool does not support a one-to-many join. To achieve a one-to-many join, use the Spatial Join tool.

• By default, all attributes of the join features will be joined to attributes of the target features. You can define which attributes will be in the joined output using the Field Map parameter.

• Use the Field Map parameter to manage the fields and their content in the output dataset.

  • Add and remove fields from the fields list, reorder the fields list, and rename fields.
  • The default data type of an output field is the same as the data type of the first input field (of that name) it encounters. You can change the data type to another valid data type.
  • Use an action to determine how values from one or multiple input fields will be merged into a single output field. The available actions are First, Last, Concatenate, Sum, Mean, Median, Mode, Minimum, Maximum, Standard Deviation, and Count.
  • When using the Concatenate action, you can specify a delimiter such as a comma or other characters. Click the start of the Delimiter text box to add the delimiter characters.
  • Standard Deviation is not a valid option for single input values.
  • Use the Slice Text button on text source fields to choose which characters from an input value will be extracted to the output field. To access the Slice Text button, hover over a text field in the input fields list; then specify the start and end character positions.
  • Fields can also be mapped using Python scripts.

• Merge rules specified in the Field Map of Join Features parameter only apply to attributes from the join features and when more than one feature is matched to a target feature (when Join_Count > 1). For example, if three features with DEPTH attribute values of 15.5, 2.5, and 3.3 are joined, and a merge rule of Mean is applied, the output field will have a value of 6.1. Null values in join fields are ignored for statistic calculation. For example, 15.5, <null>, and 2.5 will result in 9.0 for Mean and 2 for Count.

• When the Match Option parameter is set to Closest or Closest geodesic, two or more join features may be the same distance from the target feature. When this occurs, one of the join features will be randomly selected as the matching feature (the join feature's Object ID does not influence this random selection). To find the second, third, or nth closest feature, use the Generate Near Table tool.

  Learn more about how proximity is calculated

• If a join feature has a spatial relationship with multiple target features, it will be counted as many times as it is matched with the target feature. For example, if a point is within three polygons, the point will be counted three times, once for each polygon.

• For more information about using the Intersect 3D and Within a distance 3D spatial relationships, see Select By Location: 3D relationships.

Parameters

Dialog

Label	Explanation	Data Type
Target Features	The attributes from the target features and the attributes from the join features will be joined to the target features layer. However, a subset of attributes can be defined using the Field Map parameter.	Feature Layer
Join Features	The attributes from the join features will be joined to the attributes of the target features. See the explanation of the Join Operation parameter for details on how the aggregation of joined attributes are affected by the type of join operation.	Feature Layer
Join Operation (Optional)	This parameter is hidden and is not supported. All joins will be performed as a one-to-one join. To achieve a one-to-many join when the output is created in an output feature class, use the Spatial Join tool.	String
Keep All Target Features (Optional)	Specifies whether only target features with a spatial relationship with a join feature (known as an inner join) will be preserved or all target features will be preserved, even without a spatial relationship with the join features (known as an outer join). Checked—All features in the target features layer will be preserved. This is the default. Unchecked—Only those features in the target features layer with a spatial relationship with a join feature will be preserved.	Boolean
Field Map (Optional)	The fields that will be temporarily joined to the target dataset with their respective properties and source fields. All fields from the join dataset will be included by default. Use the field map to add, delete, rename, and reorder fields, as well as change other field properties. The field map can be used to combine values from two or more input fields into a single output field.	Field Mappings
Match Option (Optional)	Specifies the criteria that will be used to match rows. Intersect—The features in the join features will be matched if they intersect a target feature. This is the default. Specify the distance in the Search Radius parameter. Intersect 3D— The features in the join features will be matched if they intersect a target feature in three-dimensional space (x, y, and z). Specify the distance in the Search Radius parameter. Within a distance—The features in the join features will be matched if they are within a specified distance of a target feature. Specify the distance in the Search Radius parameter. Within a distance geodesic—This is the same as Within a distance except that geodesic distance is used rather than planar distance. 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 this option if the data covers a large geographic extent or the coordinate system of the inputs is unsuitable for distance calculations. Within a distance 3D—The features in the join features will be matched if they are within a specified distance of a target feature in three-dimensional space. Specify the distance in the Search Radius parameter. Contains—The features in the join features will be matched if a target feature contains them. The target features must be polygons or polylines. For this option, the target features cannot be points, and the join features can only be polygons when the target features are also polygons. Completely contains—The features in the join features will be matched if a target feature completely contains them. A polygon can completely contain any feature. A point cannot completely contain any feature, not even a point. A polyline can completely contain only polyline and point features. Contains Clementini—This spatial relationship produces the same results as Completely contains except that if the join feature is entirely on the boundary of the target feature (no part is properly inside or outside) the feature will not be matched. 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. Within—The features in the join features will be matched if a target feature is within them. This is the opposite of Contains. For this option, the target features can only be polygons when the join features are also polygons. A point can be a join feature only if a point is the target. Completely within—The features in the join features will be matched if a target feature is completely within them. This is the opposite of Completely contains. Within Clementini—The result will be identical to Within except if the entirety of the feature in the join features is on the boundary of the target feature, the feature will not be matched. 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 to—The features in the join features will be matched if they are identical to a target feature. Both join and target feature must be of the same shape type—point to point, line to line, or polygon to polygon. Boundary touches—The features in the join features will be matched if they have a boundary that touches a target feature. When the target and join features are lines or polygons, the boundary of the join feature can only touch the boundary of the target feature and no part of the join feature can cross the boundary of the target feature. Share a line segment with—The features in the join features will be matched if they share a line segment with a target feature. The join and target features must be lines or polygons. Crossed by the outline of—The features in the join features will be matched if a target feature is crossed by their outline. The join and target features must be lines or polygons. If polygons are used for the join or target features, the polygon's boundary (line) will be used. Lines that cross at a point will be matched; lines that share a line segment will not be matched. Have their center in—The features in the join features will be matched if a target feature's center falls within them. The center of the feature is calculated as follows: For polygon and multipoint, the geometry's centroid is used, and for line input, the geometry's midpoint is used. Specify the distance in the Search Radius parameter. Closest—The feature in the join features that is closest to a target feature will be matched. See the usage tip for more information. Specify the distance in the Search Radius parameter. Closest geodesic—This is the same as Closest except that geodesic distance is used rather than planar distance. Use this option if the data covers a large geographic extent or the coordinate system of the inputs is unsuitable for distance calculations Largest overlap—The feature in the join features will be matched with the target feature with the largest overlap.	String
Search Radius (Optional)	Join features within this distance of a target feature will be considered for the spatial join. A search radius is only valid when the spatial relationship is specified (the Match Option parameter is set to Intersect, Within a distance, Within a distance geodesic, Have their center in, Closest, or Closest geodesic). For example, using a search radius of 100 meters with the Within a distance spatial relationship will join feature within 100 meters of a target feature. For the three Within a distance relationships, if no value is specified for Search Radius, a distance of 0 is used.	Linear Unit
Distance Field Name (Optional)	The name of the field that contains the distance between the target feature and the closest join feature. This field will be added to the join. This parameter is only valid when the spatial relationship is specified (Match Option is set to Closest or Closest geodesic). The value of this field is -1 if no feature is matched within a search radius. If no field name is provided, the field will not be added to the join.	String
Permanently Join Fields (Optional)	Specifies whether fields from the join feature class will be temporarily added to the layer or permanently added to the target feature class. Unchecked—The fields of the joined feature class will be temporarily added to the layer by an inner join. This is the default. Checked—The fields of the joined feature class will be permanently added to the target feature class.	Boolean
Match Fields (Optional)	Pairs of fields from the join features and target features that will be used for attribute matching. Only the records from the join features that share match field values with the target features will participate in the spatial join.	Value Table

Derived Output

Label	Explanation	Data Type
Updated Target Features	The updated input dataset.	Feature Layer

Python

arcpy.management.AddSpatialJoin(target_features, join_features, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name}, {permanent_join}, {match_fields})

Name	Explanation	Data Type
target_features	The attributes from the target features and the attributes from the join features will be joined to the target features layer. However, a subset of attributes can be defined using the field_mapping parameter.	Feature Layer
join_features	The attributes from the join features will be joined to the attributes of the target features. See the explanation of the join_operation parameter for details on how the aggregation of joined attributes are affected by the type of join operation.	Feature Layer
join_operation (Optional)	This parameter is not supported. All joins will be performed as a one-to-one join. If you are using positional arguments in Python, use a None type, an empty string ("" or ''), or the JOIN_ONE_TO_ONE keyword. To achieve a one-to-many join when the output is created in an output feature class, use the Spatial Join tool.	String
join_type (Optional)	Specifies whether only target features with a spatial relationship with a join feature (known as an inner join) will be preserved or all target features will be preserved, even without a spatial relationship with the join features (known as an outer join). KEEP_ALL—All features in the target features layer will be preserved. This is known as an outer join. This is the default. KEEP_COMMON—Only those features in the target features layer with a spatial relationship with a join feature will be preserved. This is known as an inner join.	Boolean
field_mapping (Optional)	The fields that will be temporarily joined to the target dataset with their respective properties and source fields. All fields from the join dataset will be included by default. Use the field map to add, delete, rename, and reorder fields, as well as change other field properties. The field map can be used to combine values from two or more input fields into a single output field. In Python, use the FieldMappings class to define this parameter.	Field Mappings
match_option (Optional)	Specifies the criteria that will be used to match rows. INTERSECT—The features in the join features will be matched if they intersect a target feature. This is the default. Specify the distance in the search_radius parameter. INTERSECT_3D— The features in the join features will be matched if they intersect a target feature in three-dimensional space (x, y, and z). Specify the distance in the search_radius parameter. WITHIN_A_DISTANCE—The features in the join features will be matched if they are within a specified distance of a target feature. Specify the distance in the search_radius parameter. WITHIN_A_DISTANCE_GEODESIC—This is the same as WITHIN_A_DISTANCE except that geodesic distance is used rather than planar distance. 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 this option if the data covers a large geographic extent or the coordinate system of the inputs is unsuitable for distance calculations. WITHIN_A_DISTANCE_3D—The features in the join features will be matched if they are within a specified distance of a target feature in three-dimensional space. Specify the distance in the search_radius parameter. CONTAINS—The features in the join features will be matched if a target feature contains them. The target features must be polygons or polylines. For this option, the target features cannot be points, and the join features can only be polygons when the target features are also polygons. COMPLETELY_CONTAINS—The features in the join features will be matched if a target feature completely contains them. A polygon can completely contain any feature. A point cannot completely contain any feature, not even a point. A polyline can completely contain only polyline and point features. CONTAINS_CLEMENTINI—This spatial relationship produces the same results as COMPLETELY_CONTAINS except that if the join feature is entirely on the boundary of the target feature (no part is properly inside or outside) the feature will not be matched. 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. WITHIN—The features in the join features will be matched if a target feature is within them. This is the opposite of CONTAINS. For this option, the target features can only be polygons when the join features are also polygons. A point can be a join feature only if a point is the target. COMPLETELY_WITHIN—The features in the join features will be matched if a target feature is completely within them. This is the opposite of COMPLETELY_CONTAINS. WITHIN_CLEMENTINI—The result will be identical to WITHIN except if the entirety of the feature in the join features is on the boundary of the target feature, the feature will not be matched. 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_TO—The features in the join features will be matched if they are identical to a target feature. Both join and target feature must be of the same shape type—point to point, line to line, or polygon to polygon. BOUNDARY_TOUCHES—The features in the join features will be matched if they have a boundary that touches a target feature. When the target and join features are lines or polygons, the boundary of the join feature can only touch the boundary of the target feature and no part of the join feature can cross the boundary of the target feature. SHARE_A_LINE_SEGMENT_WITH—The features in the join features will be matched if they share a line segment with a target feature. The join and target features must be lines or polygons. CROSSED_BY_THE_OUTLINE_OF—The features in the join features will be matched if a target feature is crossed by their outline. The join and target features must be lines or polygons. If polygons are used for the join or target features, the polygon's boundary (line) will be used. Lines that cross at a point will be matched; lines that share a line segment will not be matched. HAVE_THEIR_CENTER_IN—The features in the join features will be matched if a target feature's center falls within them. The center of the feature is calculated as follows: For polygon and multipoint, the geometry's centroid is used, and for line input, the geometry's midpoint is used. Specify the distance in the search_radius parameter. CLOSEST—The feature in the join features that is closest to a target feature will be matched. See the usage tip for more information. Specify the distance in the search_radius parameter. CLOSEST_GEODESIC—This is the same as CLOSEST except that geodesic distance is used rather than planar distance. Use this option if the data covers a large geographic extent or the coordinate system of the inputs is unsuitable for distance calculations LARGEST_OVERLAP—The feature in the join features will be matched with the target feature with the largest overlap.	String
search_radius (Optional)	Join features within this distance of a target feature will be considered for the spatial join. A search radius is only valid when the spatial relationship is specified (the match_option parameter is set to INTERSECT, WITHIN_A_DISTANCE, WITHIN_A_DISTANCE_GEODESIC, HAVE_THEIR_CENTER_IN, CLOSEST, or CLOSEST_GEODESIC). For example, using a search radius of 100 meters with the WITHIN_A_DISTANCE spatial relationship will join feature within 100 meters of a target feature. For the three WITHIN_A_DISTANCE relationships, if no value is specified for search_radius, a distance of 0 is used.	Linear Unit
distance_field_name (Optional)	The name of the field that contains the distance between the target feature and the closest join feature. This field will be added to the join. This parameter is only valid when the spatial relationship is specified (match_option is set to CLOSEST or CLOSEST_GEODESIC. The value of this field is -1 if no feature is matched within a search radius. If no field name is provided, the field will not be added to the join.	String
permanent_join (Optional)	Specifies whether fields from the join feature class will be temporarily added to the layer or permanently added to the target feature class. NO_PERMANENT_FIELDS—The fields of the joined feature class will be temporarily added to the layer by an inner join. This is the default. PERMANENT_FIELDS—The fields of the joined feature class will be permanently added to the target feature class.	Boolean
match_fields [[join_field, target_field],...] (Optional)	Pairs of fields from the join features and target features that will be used for attribute matching. Only the records from the join features that share match field values with the target features will participate in the spatial join.	Value Table

Derived Output

Name	Explanation	Data Type
out_feature_class	The updated input dataset.	Feature Layer

Code sample

AddSpatialJoin example 1 (stand-alone script)

The following Python script demonstrates how to use the AddSpatialJoin function in a stand-alone script.

import os
import arcpy
arcpy.env.overwriteOutput = True

# Create hexagons
out_gdb = arcpy.env.scratchGDB
hex_fc = os.path.join(out_gdb, 'out_fc_hex_2')

arcpy.management.GenerateTessellation(
    hex_fc, '-10823285.769168 4836611.80759869 -10781728.9441187 4856999.87422328', 
    'HEXAGON', '17269676,2624 Unknown', arcpy.SpatialReference(3857))

# Create 2 random points in each hexagon
count_pts = 2
pts_fc = arcpy.management.CreateRandomPoints(
    out_gdb, 'out_fc_crp_2', constraining_feature_class=hex_fc, 
    number_of_points_or_field=count_pts)[0]

# Join the point attributes based on points within the hexagons
result = arcpy.management.AddSpatialJoin(
    hex_fc, pts_fc, None, None, 'CID', 'COMPLETELY_CONTAINS')

Environments

Default Output Z Value, M Resolution, M Tolerance, Output CONFIG Keyword, Output M Domain, Output XY Domain, Output Z Domain, Output Coordinate System, Extent, Output has M values, Output has Z values, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance