Spatial Join (Analysis) |
|
Release 9.3
Last modified January 11, 2011 |
![]() ![]() ![]() Print all topics in : "Tools" |
NOTE: This topic was updated for 9.3.1.
This creates a table join in which fields from one layer's attribute table are appended to another layer's attribute table based on the relative locations of the features in the two layers.
Learn more about aggregating field values with Spatial Join.
Learn more about spatial relationships.
Usage tips
If more than one join feature is found for a target feature and you want to maintain the exact same number of output features as Target features (input features), you need to set a Join merge rule. The Join merge rule combines values from a single field for multiple rows in the join feature class when more than one join feature is found for a target feature. For example, a city land use feature class has a text field called LU containing two letter characters which indicate each polygon's land use classification, such as CO for commercial. The land use feature class is then joined to a city district polygon feature class, where the districts are the target of the spatial join. The one-to-one join operation is chosen so the new feature class will have the same number of features as the original input districts, but it will have the attributes of the land use feature class. The Join merge rule was applied to the LU classification field (with a comma as the delimiter). This produced a result where all of the LU classification codes were combined into a single value for each district: (CO, BU, RE, ET).
Merge rules only apply to fields from the Join Features and only when JOIN_ONE_TO_ONE is used. The merge rule is ignored when applied to fields from the Target features or when the join operation is JOIN_ONE_TO_MANY.
A new field called Join_Count is always added to the output feature class. Its type is long, and it indicates how many Join Features were joined to each Target feature.
By default, all target features will be found in the resulting feature class, even if no spatial relationships were found between the Join features and a target feature. If you only want Target features that have a spatial relationship to one or more Join features, uncheck the Keep All Target Feature option when using the tool dialog box, or specify KEEP_COMMON for the Join type parameter on the command line or within a script.
Learn more about Joining the attributes of features by location.
The following environment settings affect this tool: Coordinate system, Extent, XY Tolerance, Z Tolerance, M Tolerance, XY Resolution, Z Resolution, M Resolution, Output XY domain, Output Z domain, M domain, Output has M values, Output has Z values, Default Z value, Configuration keyword, Output Spatial Grid.
Command line syntax
An overview of the Command Line window
SpatialJoin_analysis <target_features> <join_features> <out_feature_class> {JOIN_ONE_TO_ONE | JOIN_ONE_TO_MANY} {KEEP_ALL | KEEP_COMMON} {field_mapping} {match_option} {search_radius} {distance_field_name}
Parameter | Explanation | Data Type |
<target_features> |
The dataset that you are joining to. The output of the join operation will contain the features from this feature class with appended columns from the join feature class. It can be any spatial data source (shapefiles, SDE feature classes, coverages, SDC, query tables, etc.) supported by ArcGIS. It can also be read-only. |
Feature Layer |
<join_features> |
The dataset that you are joining from. The attributes from this dataset are appended to the attributes of the target feature class in the output based on a spatial relation. It can be any spatial data source (shapefiles, SDE feature classes, coverages, SDC, query tables, etc.) supported by ArcGIS. It can also be read-only. |
Feature Layer |
<out_feature_class> |
A new dataset which contains the results of the join operation. |
Feature Class |
{JOIN_ONE_TO_ONE | JOIN_ONE_TO_MANY} |
The join operation describes cardinality rules associated with matching features during the join. The join options are
|
String |
{KEEP_ALL | KEEP_COMMON} |
Determine if the join will be an inner or outer join.
|
Boolean |
{field_mapping} |
The fields and field contents chosen from the inputs. Each of the unique input fields will be listed on the Field Map window and when expanded, you will see a list of all the input field occurrences (subfields). New fields can also be added. For each Field Map, you can add, rename, or delete output fields as well as set properties such as data type and merge rule. You can also delete an output field's subfields, and you can format any output field's values if the data type is text. |
Field Mappings |
{match_option} |
Defines the criteria used to match rows. The match options are:
|
String |
{search_radius} |
Only used when the Match Option is INTERSECT or CLOSEST. Join features that are within this distance of the individual input feature will be considered for the operation. The default search radius is 0. A value of 0 for the Search radius means different things to the Match Option.
|
Linear unit |
{distance_field_name} |
The name of a new field to be added to the output feature class. This field will be of type Double and will contain distances between the Target and the closest Join Features. This option is only available when the Match Option parameter is set to CLOSEST. A value of -1 in the Distance Field means there were no Join Features within the distance specified in the Search Radius parameter. If no Distance Field Name is specified, then no field will be added to the output to capture this information. |
String |
SpatialJoin_analysis C:\Data\USA.gdb\states C:\Data\USA.gdb\Cities_Major C:\Data\USA.gdb\states_major_cities.shp JOIN_ONE_TO_ONE KEEP_ALL states_fm INTERSECTS '0 Unknown'NOTE: Where states_fm is a command line field map variable that defines the output fields
Scripting syntax
About getting started with writing geoprocessing scripts
SpatialJoin_analysis (target_features, join_features, out_feature_class, join_operation, join_type, field_mapping, match_option, search_radius, distance_field_name)
Parameter | Explanation | Data Type |
target_features (Required) |
The dataset that you are joining to. The output of the join operation will contain the features from this feature class with appended columns from the join feature class. It can be any spatial data source (shapefiles, SDE feature classes, coverages, SDC, query tables, etc.) supported by ArcGIS. It can also be read-only. |
Feature Layer |
join_features (Required) |
The dataset that you are joining from. The attributes from this dataset are appended to the attributes of the target feature class in the output based on a spatial relation. It can be any spatial data source (shapefiles, SDE feature classes, coverages, SDC, query tables, etc.) supported by ArcGIS. It can also be read-only. |
Feature Layer |
out_feature_class (Required) |
A new dataset which contains the results of the join operation. |
Feature Class |
join_operation (Optional) |
The join operation describes cardinality rules associated with matching features during the join. The join options are
|
String |
join_type (Optional) |
Determine if the join will be an inner or outer join.
|
Boolean |
field_mapping (Optional) |
The fields and field contents chosen from the inputs. Each of the unique input fields will be listed on the Field Map window and when expanded, you will see a list of all the input field occurrences (subfields). New fields can also be added. For each Field Map, you can add, rename, or delete output fields as well as set properties such as data type and merge rule. You can also delete an output field's subfields, and you can format any output field's values if the data type is text. |
Field Mappings |
match_option (Optional) |
Defines the criteria used to match rows. The match options are:
|
String |
search_radius (Optional) |
Only used when the Match Option is INTERSECT or CLOSEST. Join features that are within this distance of the individual input feature will be considered for the operation. The default search radius is 0. A value of 0 for the Search radius means different things to the Match Option.
|
Linear unit |
distance_field_name (Optional) |
The name of a new field to be added to the output feature class. This field will be of type Double and will contain distances between the Target and the closest Join Features. This option is only available when the Match Option parameter is set to CLOSEST. A value of -1 in the Distance Field means there were no Join Features within the distance specified in the Search Radius parameter. If no Distance Field Name is specified, then no field will be added to the output to capture this information. |
String |
# Create the geoprocessor object import arcgisscripting, sys gp = arcgisscripting.create() # Want to join USA cities to states and calculate the mean city population # for each state targetFeatures = "C:/data/USA.gdb/states" joinFeatures = "C:/data/USA.gdb/cities" # Output will be the target features, states, with a mean city population field (mcp) outfc = "C:/data/USA.gdb/states_mcp" # Create a new fieldmappings and add the two input feature classes. fieldmappings = gp.CreateObject("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. fieldmap = fieldmappings.GetFieldMap(fieldmappings.FindFieldMapIndex("POP1990")) # 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(fieldmappings.FindFieldMapIndex("POP1990"), 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) x = fieldmappings.findfieldmapindex("CITY_FIPS") fieldmappings.removefieldmap(x) #Run the Spatial Join tool, using the defaults for the join operation and join type gp.SpatialJoin(targetFeatures, joinFeatures, outfc, "#", "#", fieldmappings)