Join Features

The JoinFeatures task works with two layers and joins the attributes from one feature to another based on spatial and attribute relationships.

Request URL

http://<analysis url>/JoinFeatures/SubmitJob

Request parameters

Parameter	Description
targetLayer (Required)	The point, line, polygon, or table layer that will have attributes from the joinLayer parameter appended to its table. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following: A URL to a feature service layer with an optional filter to select specific features A feature collection Examples: {"url": <feature service layer url>, "filter": <where clause>} {"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}
joinLayer (Required)	The point, line, polygon, or table layer that will be joined to the targetLayer parameter value. Syntax: As described in detail in the Feature input topic, this parameter can be one of the following: A URL to a feature service layer with an optional filter to select specific features A feature collection
spatialRelationship	Specifies the spatial relationship that will be used to spatially join features. Values: IdenticalTo | Intersects | CompletelyContains | CompletelyWithin | WithinDistance | Contains | Within.
spatialRelationshipDistance (Required if spatialRelationship is WithinDistance)	A double value used for the search distance to determine if the targetFeatures values are near or within a specified distance of the joinFeatures values. This is only applied if WithinDistance is specified for the spatialRelationship parameter. You can only enter a single distance value. The units of the distance values are supplied by the spatialRelationshipDistanceUnits parameter. Examples: "spatialRelationshipDistance": 4 "spatialRelationshipDistance": 53.4
spatialRelationshipDistanceUnits (Required if spatialRelationship is WithinDistance)	The linear unit to be used with the distance value specified in spatialRelationshipDistance. The default is Miles. Values: Miles | Yards | Feet | NauticalMiles | Meters | Kilometers
attributeRelationship	The attribute relationship used to join features. Features are matched when the field values in the join layer are equal to the field values in the target layer. Syntax: "attributeRelationship": [{"targetField":"<targetLayer fieldname>","operator":"equal","joinField":"<joinLayer fieldname>"}] Examples: //Example one [{"targetField":"ZipArea","operator":"equal","joinField":"ZipCode"}] //Example two [{"targetField":"ownerID","operator":"equal","joinField":"InsuranceClaim"}]
joinOperation	A string representing the type of join that will be applied: JoinOneToOne—If multiple join features are found that have the same relationship with a single target feature, the attributes from the multiple join features will be aggregated using the specified summary statistics. 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 SummaryField value of sum is specified, the aggregated value in the output feature class will be 10. When summaryFields values are specified, the output will also include a Count field, which specifies the number of features that were aggregated. If no summaryFields values are specified, only one matching record from the join layer will be returned for each target feature. The matching record that is returned is determined by the recordsToMatch expression. JoinOneToOne is the default. JoinOneToMany—If multiple join features are found that have the same 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 the first polygon, and another record with the attributes of the second polygon. There are no summary statistics calculated with this method. Note: Adding summary statistics is not supported for JoinOneToMany operations. Values: JoinOneToOne | JoinOneToMany.
summaryFields	A list of field names and statistical summary types that will be calculated. The count is always returned when you calculate a statistic. Note: fieldName is the name of one of the numeric fields found in the input joinLayer value. Syntax: [{"statisticType":"<statistic type>","onStatisticField":"<joinLayer fieldName>"}, ...] statisticType is one of the following: SUM—Adds the total value of all the points in each polygon MEAN—Calculates the average of all the points in each polygon MIN—Finds the smallest value of all the points in each polygon MAX—Finds the largest value of all the points in each polygon STDDEV—Finds the standard deviation of all the points in each polygon Example: [{"statisticType":"MEAN","onStatisticField":"Total_Sales"}] In ArcGIS Online or ArcGIS Enterprise 11.2 and later, you can calculate the count only. To only calculate the count, specify the count statistic without a field: Example: [{"statisticType":"COUNT","onStatisticField":null}]
recordsToMatch	The feature from the joinLayer parameter that will be joined to the target feature when multiple join features have the same relationship with a single target feature. The feature that is joined is the first matching record when the features are sorted by the field listed in the orderByFields parameter in either ascending or descending order. The recordsToMatch parameter is not applied if you specify a spatialRelationship parameter. Syntax: {"groupByFields":"","orderByFields":"<joinLayer fieldname> <ORDER>","topCount":1} Examples: //Example one - joins the first matching feature {"groupByFields":"","orderByFields":"objectid ASC","topCount":1} //Example two - joins the feature with the highest population {"groupByFields":"","orderByFields":"population DESC","topCount":1}
outputName	If provided, the task will create a feature service of the results. You define the name of the service. If an outputName value is not provided, the task will return a feature collection. Syntax: { "serviceProperties": { "name": "<service name>" } } In ArcGIS Online or ArcGIS Enterprise 10.9.1 and later, you can overwrite an existing feature service by providing the itemId value of the existing feature service and setting the overwrite property to true. Including the serviceProperties parameter is optional. As described in the Feature output topic, you must either be the owner of the feature service or have administrative privileges to perform the overwrite. Syntax: { "itemProperties": { "itemId": "<itemID of the existing feature service>", "overwrite": true } } or { "serviceProperties": { "name": "<existing service name>" }, "itemProperties": { "itemId": "<itemID of the existing feature service>", "overwrite": true } }
context	The Context parameter contains the following additional settings that affect task operation: Extent (extent)—A bounding box that defines the analysis area. Only input features that intersect the bounding box will be analyzed. Output spatial reference (outSR)—The output features will be projected into the output spatial reference. Syntax: { "extent" : {extent}, "outSR" : {spatial reference} }
joinType	Specifies the type of join that will be used to determine which target features are returned: Inner—Only target features that match one or more join features will be returned. This is the default. Left—All target features will be returned.
f	The response format. The default response format is html. Values: html | json | kmz

Response

When you submit a request, the service assigns a unique job ID for the transaction.

Syntax:

{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use the jobId value to periodically check the status of the job and messages as described in Checking job status. Once the job has successfully completed, use the jobId value to retrieve the results. To track the status, you can make a request of the following form:

http://<analysis url>/JoinFeatures/jobs/<jobId>

Access results

When the status of the job request is esriJobSucceded, you can access the results of the analysis by making a request of the following form:

http://<analysis url>/JoinFeatures/jobs/<jobId>/results/outputLayer?token=<your token>&f=json

Parameter

Description

outputLayer

The outputLayer value will have the same geometry as the targetLayer value. The targetLayer value will inherit all the attributes of the joined joinLayer value. If the JoinOneToOne operation is applied, the output value will have a Count attribute, which is the number of features that match the join conditions. If the summaryFields parameter is specified in the task request, the layer will have additional attributes for each requested summary. For example, if you request the following: [{"statisticType":"SUM","onStatisticField":"Total_Sales"},{"statisticType":"MEAN","onStatisticField":"Total_Sales"}] The result polygon features will have two attributes, Sum_Total_Sales and Mean_Total_Sales, to contain the calculated values. If the JoinOneToMany operation is applied, the output value will have each pair of joined features. Example: {"url": "http://<analysis url>/JoinFeatures/jobs/<jobId>/results/outputLayer"} The result has properties for parameter name, data type, and value. The contents of value depend on the OutputName parameter value provided in the initial request. If an OutputName value was provided, value contains the URL to the feature service layer. { "paramName":"output", "dataType":"GPString", "value":{"url":"<hosted featureservice layer url>"} } If no OutputName value was provided, value contains a feature collection. { "paramName":"output", "dataType":"GPString", "value":{"layerDefinition": {}, "featureSet": {} } } See Feature output for more information about how the result layer or collection is accessed.