Show Navigation | Hide Navigation
You are here:
Geoprocessing tool reference > Analysis toolbox > Overlay toolset > Tools

Spatial Join (Analysis)

Release 9.3
Last modified January 11, 2011
E-mail This Topic Printable Version Give Us Feedback

Print all topics in : "Tools"


Related Topics

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

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

  • JOIN_ONE_TO_ONE — This means that the number of rows in the output matches the number of rows in the target feature class. If more than one feature from the join feature class matches a target feature, the attributes of the join features are aggregated in the result. For example, a point within polygon join where several points are within a single polygon results in the aggregation of the points attributes. The aggregation is based on the options set in the field map control. This is the default.
  • JOIN_ONE_TO_MANY — The means that for each row in the target feature class, there can be several rows in the output feature class. With this option, attributes are never aggregated. For example, a point within polygon join where several points are within a single polygon results in a polygon for each matching point in the output feature class.

String
{KEEP_ALL | KEEP_COMMON}

Determine if the join will be an inner or outer join.

  • KEEP_ALL — All records in the input layer or table view will be included in the output; also known as an outer join. This is the default.
  • KEEP_COMMON — Only those records in the input that match to a row in the join table will be present in the result; also known as an inner 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.

Learn more about choosing and setting the output fields.

Field Mappings
{match_option}

Defines the criteria used to match rows. The match options are:

  • INTERSECTS — Matches join features that intersect target features.
  • CONTAINS — Matches occur when a target feature contains a join feature. Points can't be set as target features and polygons can only be set as join features when the target features are also polygons.
  • IS_WITHIN — Target features within join features are matched. Points can't be set as join features and polygons can only be set as target features when the join features are also polygons.
  • CLOSEST — The Target features will be matched to the closest join feature.

Learn more about spatial relationships.

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.

  • INTERSECT: Only the join features that INTERSECT the input feature will be included in the join.
  • CLOSEST: All join features will be candidates for each input feature. Basically, a value of 0 here means use all join features.

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
Data types for geoprocessing tool parameters


Command line example

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

  • JOIN_ONE_TO_ONE — This means that the number of rows in the output matches the number of rows in the target feature class. If more than one feature from the join feature class matches a target feature, the attributes of the join features are aggregated in the result. For example, a point within polygon join where several points are within a single polygon results in the aggregation of the points attributes. The aggregation is based on the options set in the field map control. This is the default.
  • JOIN_ONE_TO_MANY — The means that for each row in the target feature class, there can be several rows in the output feature class. With this option, attributes are never aggregated. For example, a point within polygon join where several points are within a single polygon results in a polygon for each matching point in the output feature class.

String
join_type (Optional)

Determine if the join will be an inner or outer join.

  • KEEP_ALL — All records in the input layer or table view will be included in the output; also known as an outer join. This is the default.
  • KEEP_COMMON — Only those records in the input that match to a row in the join table will be present in the result; also known as an inner 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.

Learn more about choosing and setting the output fields.

Field Mappings
match_option (Optional)

Defines the criteria used to match rows. The match options are:

  • INTERSECTS — Matches join features that intersect target features.
  • CONTAINS — Matches occur when a target feature contains a join feature. Points can't be set as target features and polygons can only be set as join features when the target features are also polygons.
  • IS_WITHIN — Target features within join features are matched. Points can't be set as join features and polygons can only be set as target features when the join features are also polygons.
  • CLOSEST — The Target features will be matched to the closest join feature.

Learn more about spatial relationships.

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.

  • INTERSECT: Only the join features that INTERSECT the input feature will be included in the join.
  • CLOSEST: All join features will be candidates for each input feature. Basically, a value of 0 here means use all join features.

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

Data types for geoprocessing tool parameters


Script example

# 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)

Please visit the Feedback page to comment or give suggestions on ArcGIS Desktop Help.
Copyright © Environmental Systems Research Institute, Inc.