Spatial Join (Analysis)—ArcGIS Pro

Summary

Joins attributes from one feature to another based on the spatial relationship. The target features and the joined attributes from the join features are written to the output feature class.

View spatial relationship examples

Usage

A spatial join matches rows from the Join Features values to the Target Features values based on their relative spatial locations.
By default, all attributes of the join features are appended to attributes of the target features and copied to the output feature class. You can define which attributes will be written to the output by manipulating them in the Field Map of Join Features parameter.
Two new fields, Join_Count and TARGET_FID, are added to the output feature class. The Join_Count field indicates the number of join features that match each target feature (TARGET_FID).
Another new field, JOIN_FID, is added to the output when Join one to many (JOIN_ONE_TO_MANY in Python) is specified in the Join Operation (join_operation in Python) parameter .
When the Join Operation parameter is Join one to many, there can be more than one row in the output feature class for each target feature. Use the JOIN_FID field to determine which feature is joined to which target feature (TARGET_FID). A value of -1 for the JOIN_FID field means no feature meets the specified spatial relationship with the target feature.
All input target features are written to the output feature class if both the following apply:
- Join Operation is set to Join one to one.
- Keep All Target Features is checked (join_type = "KEEP_ALL" in Python).
All fields in the output dataset and the contents of those fields can be controlled using the Field map.
- To change the field order, select a field name and drag it to the preferred position.
- 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 manually change the data type at any time to any other valid data type.
- The following merge rules are available: first, last, join, sum, mean, median, mode, minimum, maximum, standard deviation, and count.
- When using the Join merge rule, you can specify a delimiter such as a space, comma, period, dash, and so on. To use a space, make sure the pointer is at the start of the input box and press the Spacebar once.
- You can specify the start and end positions of text fields using the format option.
- Do not perform standard deviation on a single input because values cannot be divided by zero, so standard deviation is not a valid option for single inputs.
Learn more about mapping fields in 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, it is possible that two or more join features are at the same distance from the target feature. When this situation occurs, one of the join features is randomly selected as the matching feature (the join feature's Object ID does not influence this random selection). To find the 2^nd, 3^rd, or N^th 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 is counted as many times as it is matched with the target feature. For example, if a point is within three polygons, the point is counted three times, once for each polygon.
For more information about using the three-dimensional spatial relationships Intersect 3D and Within a distance 3D see Select By Location: 3D relationships.

Parameters

Label	Explanation	Data Type
Target Features	Attributes of the target features and the attributes from the joined features will be transferred to the output feature class. However, a subset of attributes can be defined in 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
Output Feature Class	A new feature class containing the attributes of the target and join features. By default, all attributes of target features and the attributes of the joined features will be written to the output. However, the set of attributes to be transferred can be controlled by the field map parameter.	Feature Class
Join Operation (Optional)	Specifies how joins between the target features and join features will be handled in the output feature class if multiple join features are found that have the same spatial relationship with a single target feature. Join one to one — If multiple join features are found that have the same spatial relationship with a single target feature, the attributes from the multiple join features will be aggregated using a field map merge rule. For example, if a point target feature is found within two separate polygon join features, the attributes from the two polygons will be aggregated before being transferred to the output point feature class. If one polygon has an attribute value of 3 and the other has a value of 7, and a Sum merge rule is specified, the aggregated value in the output feature class will be 10. This is the default. Join one to many — If multiple join features are found that have the same spatial relationship with a single target feature, the output feature class will contain multiple copies (records) of the target feature. For example, if a single point target feature is found within two separate polygon join features, the output feature class will contain two copies of the target feature: one record with the attributes of one polygon and another record with the attributes of the other polygon.	String
Keep All Target Features (Optional)	Specifies whether all target features will be maintained in the output feature class (known as outer join) or only those that have the specified spatial relationship with the join features (inner join). Checked—All target features will be maintained in the output (outer join). This is the default. Unchecked—Only those target features that have the specified spatial relationship with the join features will be maintained in the output feature class (inner join). For example, if a point feature class is specified for the target features, and a polygon feature class is specified for the join features, with a Match Option value of Within, the output feature class will only contain those target features that are within a polygon join feature. Any target features not within a join feature will be excluded from the output.	Boolean
Field Map (Optional)	Controls which attribute fields will be in the output. By default, all fields from the inputs will be included. Fields can be added, deleted, renamed, and reordered, and you can change their properties. Merge rules allow you to specify how values from two or more input fields are merged or combined into a single output value. There are several merge rules you can use to determine how the output field will be populated with values. First—Use the input fields' first value. Last—Use the input fields' last value. Join—Concatenate (join) the input field values. Sum—Calculate the total of the input field values. Mean—Calculate the mean (average) of the input field values. Median—Calculate the median (middle) of the input field values. Mode—Use the value with the highest frequency. Min—Use the minimum value of all the input field values. Max—Use the maximum value of all the input field values. Standard deviation—Use the standard deviation classification method on all the input field values. Count—Find the number of records included in the calculation.	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 a 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 a 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 a distance in the Search Radius parameter. Within a distance geodesic —Same as Within a distance except that geodesic distance is used rather than planar distance. Choose this if your 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 a 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. Polygon can completely contain any feature. Point cannot completely contain any feature, not even a point. Polyline can completely contain only polyline and point. Contains Clementini —This spatial relationship yields the same results as Completely contains with the exception 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. It is opposite to Contains. For this option, the target features can only be polygons when the join features are also polygons. Point can be join feature only if point is target. Completely within —The features in the join features will be matched if a target feature is completely within them. This is opposite to 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 same shape type—point-to-point, line-to-line, and 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, not lines that share a line segment. 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 a distance in the Search Radius parameter. Closest —The feature in the join features that is closest to a target feature is matched. See the usage tip for more information. Specify a distance in the Search Radius parameter. Closest geodesic —Same as Closest except that geodesic distance is used rather than planar distance. Choose this if your data covers a large geographic extent or the coordinate system of the inputs is unsuitable for distance calculations	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 spatial relationship Within a distance 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 a field, which will be added to the output feature class, that contains the distance between the target feature and the closest join feature. 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 specified, the field will not be added to the output feature class.	String

arcpy.analysis.SpatialJoin(target_features, join_features, out_feature_class, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name})

Name	Explanation	Data Type
target_features	Attributes of the target features and the attributes from the joined features will be transferred to the output feature class. However, a subset of attributes can be defined in 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
out_feature_class	A new feature class containing the attributes of the target and join features. By default, all attributes of target features and the attributes of the joined features will be written to the output. However, the set of attributes to be transferred can be controlled by the field map parameter.	Feature Class
join_operation (Optional)	Specifies how joins between the target features and join features will be handled in the output feature class if multiple join features are found that have the same spatial relationship with a single target feature. JOIN_ONE_TO_ONE —If multiple join features are found that have the same spatial relationship with a single target feature, the attributes from the multiple join features will be aggregated using a field map merge rule. For example, if a point target feature is found within two separate polygon join features, the attributes from the two polygons will be aggregated before being transferred to the output point feature class. If one polygon has an attribute value of 3 and the other has a value of 7, and a Sum merge rule is specified, the aggregated value in the output feature class will be 10. This is the default. JOIN_ONE_TO_MANY —If multiple join features are found that have the same spatial relationship with a single target feature, the output feature class will contain multiple copies (records) of the target feature. For example, if a single point target feature is found within two separate polygon join features, the output feature class will contain two copies of the target feature: one record with the attributes of one polygon and another record with the attributes of the other polygon.	String
join_type (Optional)	Specifies whether all target features will be maintained in the output feature class (known as outer join) or only those that have the specified spatial relationship with the join features (inner join). KEEP_ALL —All target features will be maintained in the output (outer join). This is the default. KEEP_COMMON — Only those target features that have the specified spatial relationship with the join features will be maintained in the output feature class (inner join). For example, if a point feature class is specified for the target features, and a polygon feature class is specified for the join features, with match_option = "WITHIN", the output feature class will only contain those target features that are within a polygon join feature. Any target features not within a join feature will be excluded from the output.	Boolean
field_mapping (Optional)	Controls which attribute fields will be in the output. By default, all fields from the inputs will be included. Fields can be added, deleted, renamed, and reordered, and you can change their properties. Merge rules allow you to specify how values from two or more input fields are merged or combined into a single output value. There are several merge rules you can use to determine how the output field will be populated with values. First—Use the input fields' first value. Last—Use the input fields' last value. Join—Concatenate (join) the input field values. Sum—Calculate the total of the input field values. Mean—Calculate the mean (average) of the input field values. Median—Calculate the median (middle) of the input field values. Mode—Use the value with the highest frequency. Min—Use the minimum value of all the input field values. Max—Use the maximum value of all the input field values. Standard deviation—Use the standard deviation classification method on all the input field values. Count—Find the number of records included in the calculation. In Python, you can 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 a 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 a 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 a distance in the search_radius parameter. WITHIN_A_DISTANCE_GEODESIC —Same as WITHIN_A_DISTANCE except that geodesic distance is used rather than planar distance. Choose this if your 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 a 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. Polygon can completely contain any feature. Point cannot completely contain any feature, not even a point. Polyline can completely contain only polyline and point. CONTAINS_CLEMENTINI —This spatial relationship yields the same results as COMPLETELY_CONTAINS with the exception 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. It is opposite to CONTAINS. For this option, the target features can only be polygons when the join features are also polygons. Point can be join feature only if point is target. COMPLETELY_WITHIN —The features in the join features will be matched if a target feature is completely within them. This is opposite to 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 same shape type—point-to-point, line-to-line, and 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, not lines that share a line segment. 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 a distance in the search_radius parameter. CLOSEST —The feature in the join features that is closest to a target feature is matched. See the usage tip for more information. Specify a distance in the search_radius parameter. CLOSEST_GEODESIC —Same as CLOSEST except that geodesic distance is used rather than planar distance. Choose this if your data covers a large geographic extent or the coordinate system of the inputs is unsuitable for distance calculations	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 (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 spatial relationship WITHIN_A_DISTANCE 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 a field, which will be added to the output feature class, that contains the distance between the target feature and the closest join feature. 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 specified, the field will not be added to the output feature class.	String

Code sample

SpatialJoin example 1 (Python window)

The following script demonstrates how to use the SpatialJoin function in a Python window.

import arcpy

target_features = "C:/data/usa.gdb/states"
join_features = "C:/data/usa.gdb/cities"
out_feature_class = "C:/data/usa.gdb/states_cities"

arcpy.SpatialJoin_analysis(target_features, join_features, out_feature_class)

SpatialJoin example 2 (stand-alone script)

The following stand-alone script demonstrates how to use the SpatialJoin function to join attributes of cities to states.

# Name: SpatialJoin_Example2.py
# Description: Join attributes of cities to states based on spatial relationships.
# Requirements: os module

# Import system modules
import arcpy
import os

# Set local variables
workspace = r"C:\gpqa\mytools\spatialjoin\usa.gdb"
outWorkspace = r"C:\gpqa\mytools\spatialjoin\output.gdb"
 
# Want to join USA cities to states and calculate the mean city population
# for each state
targetFeatures = os.path.join(workspace, "states")
joinFeatures = os.path.join(workspace, "cities")
 
# Output will be the target features, states, with a mean city population field (mcp)
outfc = os.path.join(outWorkspace, "states_mcp2")
 
# Create a new fieldmappings and add the two input feature classes.
fieldmappings = arcpy.FieldMappings()
fieldmappings.addTable(targetFeatures)
fieldmappings.addTable(joinFeatures)
 
# First get the POP1990 fieldmap. POP1990 is a field in the cities feature class.
# The output will have the states with the attributes of the cities. Setting the
# field's merge rule to mean will aggregate the values for all of the cities for
# each state into an average value. The field is also renamed to be more appropriate
# for the output.
pop1990FieldIndex = fieldmappings.findFieldMapIndex("POP1990")
fieldmap = fieldmappings.getFieldMap(pop1990FieldIndex)
 
# Get the output field's properties as a field object
field = fieldmap.outputField
 
# Rename the field and pass the updated field object back into the field map
field.name = "mean_city_pop"
field.aliasName = "mean_city_pop"
fieldmap.outputField = field
 
# Set the merge rule to mean and then replace the old fieldmap in the mappings object
# with the updated one
fieldmap.mergeRule = "mean"
fieldmappings.replaceFieldMap(pop1990FieldIndex, fieldmap)
 
# Delete fields that are no longer applicable, such as city CITY_NAME and CITY_FIPS
# as only the first value will be used by default
x = fieldmappings.findFieldMapIndex("CITY_NAME")
fieldmappings.removeFieldMap(x)
y = fieldmappings.findFieldMapIndex("CITY_FIPS")
fieldmappings.removeFieldMap(y)
 
#Run the Spatial Join tool, using the defaults for the join operation and join type
arcpy.SpatialJoin_analysis(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)

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

Licensing information

Basic: Yes
Standard: Yes
Advanced: Yes