Geoprocessing tool used to join the attributes of two feature classes based on the spatial relationships between the features in the two feature classes and to write the join an output.
A spatial join involves matching rows from the Join Features to the Target Features based on their relative spatial locations.
By default, all attributes of the join features are appended to attributes of the target features and copied over to the output feature class. You can define which of the 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 always added to the output feature class. Join_Count indicates how many join features 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 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. The JOIN_FID field makes it easier to determine which feature is joined to which target feature (TARGET_FID). A value of -1 for 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 only if:
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 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 FID does not influence this random selection). If you want to find the 2nd, 3rd, or N th closest feature, use the Generate Near Table tool.
If a join feature has a spatial relationship with multiple target features, then it is counted as many times as it is matched against the target feature. For example, if a point is within three polygons, then 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.
| Parameter | Explanation |
|---|---|
| target_features | Attributes of the target features and the attributes from the joined features are transferred to the output feature class. However, a subset of attributes can be defined in the field map parameter. |
| join_features | The attributes from the join features are 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. |
| out_feature_class (Optional) | 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 are written to the output. However, the set of attributes to be transferred can be controlled by the field map parameter. |
| field_mapping (Optional) | Controls which attribute fields will be in the output feature class. The initial list contains all the fields from both the target features and the join features. Fields can be added, deleted, renamed, or have their properties changed. The selected fields from the target features are transferred as is, but selected fields from the join features can be aggregated by a valid merge rule. The default value is an empty string, in which case, all fields from both target and join features are transferred to the output. For details on field mapping, see the help topics "Using the field mapping control" and "Mapping input fields to output fields." Multiple fields and statistic combination may be specified.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 that determine how the output field is populated with values.First—Use the input fields' first value.Last—Use the input fields' last value.Join—Concatenate (join) the input fields' values.Sum—Calculate the total of the input fields' values.Mean—Calculate the mean (average) of the input fields' values.Median—Calculate the median (middle) of the input fields' values.Mode—Use the value with the highest frequency.Min—Use the minimum value of all input fields' values.Max—Use the maximum value of all input fields' values.Standard deviation—Use the standard deviation classification method on all input fields' values.Count—Find the number of records included in the calculation. |
| esri_out_feature_service_name (Optional) | The name of the optional feature service to create on the federated server containing the result of this tool. If no name is specified an output feature service will not be created. |
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 SpatialJoin 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)
There are no tags for this item.
There are no credits for this item.
There are no use limitations for this item.