Label | Explanation | Data Type |
Target Features | The attributes from 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 by 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 the 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 defined by the field map parameter. | Feature Class |
Join Operation (Optional) | The operation that will join the target features and join features in the output feature class if multiple join features are found that have the same spatial relationship with a single target feature.
| String |
Keep All Target Features (Optional) | Specifies whether all target features will be maintained in the output feature class (an outer join) or only those that have the specified spatial relationship with the join features (an inner join).
| Boolean |
Field Map (Optional) | The fields that will be included in the output feature class with their respective properties and source fields. The output includes all fields from the join and target features 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.
| 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 output feature class. 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 output feature class. | String |
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 |
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.
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 using the Field Map parameter.
Two new fields, Join_Count and TARGET_FID, will be 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, will be added to the output when Join one to many is specified for the Join Operation parameter.
When the Join Operation parameter is set to 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 will be written to the output feature class if both of the following apply:
- Join Operation is set to Join one to one.
- Keep All Target Features is checked.
To permanently transfer fields to the target feature class, use the Add Spatial Join tool with its Permanently Join Fields parameter checked.
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.
Actions specified in the Field Map 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 the Mean action 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, a null value, 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.
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 in three polygons, the point will be counted three times, once for each polygon.
The Matching Attributes parameter filters the features that will be matched by the spatial relationship specified in the Match Option parameter. Specify fields from the join and target features that must have matching attributes in addition to their spatial relationship.
For more information about using the Intersect 3D and Within a distance 3D spatial relationships, see Select By Location: 3D relationships.
Parameters
arcpy.analysis.SpatialJoin(target_features, join_features, out_feature_class, {join_operation}, {join_type}, {field_mapping}, {match_option}, {search_radius}, {distance_field_name}, {match_fields})
Name | Explanation | Data Type |
target_features | The attributes from 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 by 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 the 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 defined by the field map parameter. | Feature Class |
join_operation (Optional) | The operation that will join the target features and join features in the output feature class if multiple join features are found that have the same spatial relationship with a single target feature.
| String |
join_type (Optional) | Specifies whether all target features will be maintained in the output feature class (an outer join) or only those that have the specified spatial relationship with the join features (an inner join).
| Boolean |
field_mapping (Optional) | The fields that will be included in the output feature class with their respective properties and source fields. The output includes all fields from the join and target features 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.
| 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 the 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 output feature class. 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 output feature class. | String |
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 |
Code sample
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.analysis.SpatialJoin(target_features, join_features, out_feature_class)
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.
# 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.analysis.SpatialJoin(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)
Environments
Licensing information
- Basic: Yes
- Standard: Yes
- Advanced: Yes