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. 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	Defines the spatial relationship 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 are near or within a specified distance of the joinFeatures. This is only applied if withinDistance is the selected 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	Defines an attribute relationship used to join features. Features are matched when the field values in the join layer are equal to 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 (JoinOneToOne or JoinOneToMany) 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 of sum is selected, the aggregated value in the output feature class will be 10. When summaryFields are specified, the output will also include a Count field, which specifies the number of features that were aggregated. If no summaryFields 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 you want to calculate. Note that the count is always returned by default. Note: fieldName is the name of one of the numeric fields found in the input joinLayer. 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"}]
recordsToMatch	Defines which feature from the joinLayer is 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. 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 outputName is not supplied, 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 of the existing feature service and setting the overwrite property as 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	Context contains additional settings that affect task execution. There are two settings: 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	The type of join used to determine which target features are returned, Inner or Left: Inner—Only target features that match one or more join features are returned. This is the default. Left—Returns all target features.
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 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 to retrieve the results. To track the status, you can make a request of the following form:

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

Accessing 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 will have the same geometry as the targetLayer. The targetLayer will inherit all the attributes of the joined joinLayer. If a JoinOneToOne is applied, the output will have a Count attribute, which is the number of features that match the join conditions. If a 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 a JoinOneToMany is applied, the output 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 provided in the initial request. If OutputName is provided, value contains the URL to the feature service layer. { "paramName":"output", "dataType":"GPString", "value":{"url":"<hosted featureservice layer url>"} } If OutputName is not 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.