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

Use dark colors for code blocksCopy
http://<analysis url>/JoinFeatures/SubmitJob

Request parameters

Parameter Description

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: Use dark colors for code blocksCopy `1 2 "spatialRelationshipDistance": 4 "spatialRelationshipDistance": 53.4`
`spatialRelationshipDistanceUnits` (Required if `spatialRelationship` is `WithinDistance`)	The linear unit to be used with the distance value specified in `spatialRelationshipDistance`. 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: Use dark colors for code blocksCopy `1 "attributeRelationship": [{"targetField":"<targetLayer fieldname>","operator":"equal","joinField":"<joinLayer fieldname>"}]` Examples: Use dark colors for code blocksCopy `1 2 3 4 //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 one of the numeric or date fields from the `joinLayer` parameter. Syntax: Use dark colors for code blocksCopy `1 [{"statisticType":"<statistic type>","onStatisticField":"<joinLayer fieldName>"}, ...]` `statisticType` is one of the following: `SUM`—Adds the total value of all the matching records in the `joinLayer` for each record in the `targetLayer`. This statistic type is not supported for date fields. `MEAN`—Calculates the average value of all the matching records in the `joinLayer` for each record in the `targetLayer`. This statistic type is not supported for date fields. `MIN`—Finds the smallest value of all the matching records in the `joinLayer` for each record in the `targetLayer`. This statistic type is supported for date fields. `MAX`—Finds the largest value of all the matching records in the `joinLayer` for each record in the `targetLayer`. This statistic type is supported for date fields. `STDDEV`—Finds the standard deviation of all the matching records in the `joinLayer` for each record in the `targetLayer`. This statistic type is not supported for date fields. Example: Use dark colors for code blocksCopy `1 [{"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: Use dark colors for code blocksCopy `1 [{"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: Use dark colors for code blocksCopy `1 {"groupByFields":"","orderByFields":"<joinLayer fieldname> <ORDER>","topCount":1}` Examples: Use dark colors for code blocksCopy `1 2 3 4 //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: Use dark colors for code blocksCopy `1 2 3 4 5 { "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: Use dark colors for code blocksCopy `1 2 3 4 5 6 7 { "itemProperties": { "itemId": "<itemID of the existing feature service>", "overwrite": true } }` or Use dark colors for code blocksCopy `1 2 3 4 5 6 7 8 9 { "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: Use dark colors for code blocksCopy `1 2 3 4 { "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`

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.

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:

Use dark colors for code blocksCopy
"spatialRelationshipDistance": 4
"spatialRelationshipDistance": 53.4

spatialRelationshipDistanceUnits

(Required if spatialRelationship is WithinDistance)

The linear unit to be used with the distance value specified in spatialRelationshipDistance.

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:

Use dark colors for code blocksCopy
"attributeRelationship": [{"targetField":"<targetLayer fieldname>","operator":"equal","joinField":"<joinLayer fieldname>"}]

Examples:

Use dark colors for code blocksCopy
//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.

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.

Syntax:

Use dark colors for code blocksCopy
[{"statisticType":"<statistic type>","onStatisticField":"<joinLayer fieldName>"}, ...]

statisticType is one of the following:

SUM—Adds the total value of all the matching records in the joinLayer for each record in the targetLayer. This statistic type is not supported for date fields.
MEAN—Calculates the average value of all the matching records in the joinLayer for each record in the targetLayer. This statistic type is not supported for date fields.
MIN—Finds the smallest value of all the matching records in the joinLayer for each record in the targetLayer. This statistic type is supported for date fields.
MAX—Finds the largest value of all the matching records in the joinLayer for each record in the targetLayer. This statistic type is supported for date fields.
STDDEV—Finds the standard deviation of all the matching records in the joinLayer for each record in the targetLayer. This statistic type is not supported for date fields.

Example:

Use dark colors for code blocksCopy
[{"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:

Use dark colors for code blocksCopy
[{"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:

Use dark colors for code blocksCopy
{"groupByFields":"","orderByFields":"<joinLayer fieldname> <ORDER>","topCount":1}

Examples:

Use dark colors for code blocksCopy
//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:

Use dark colors for code blocksCopy
{
  "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:

Use dark colors for code blocksCopy
{

  "itemProperties": {
			"itemId": "<itemID of the existing feature service>",
			"overwrite": true
	}
}

Use dark colors for code blocksCopy
{
"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:

Use dark colors for code blocksCopy
{
  "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

Response

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

Use dark colors for code blocksCopy
{
  "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 Check 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:

Use dark colors for code blocksCopy
http://<analysis url>/JoinFeatures/jobs/<jobId>

Access results

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

Use dark colors for code blocksCopy
http://<analysis url>/JoinFeatures/jobs/<jobId>/results/outputLayer?token=<your token>&f=json

Parameter Description

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: Use dark colors for code blocksCopy `1 [{"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: Use dark colors for code blocksCopy `1 {"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. Use dark colors for code blocksCopy `1 2 3 4 5 { "paramName":"output", "dataType":"GPString", "value":{"url":"<hosted featureservice layer url>"} }` If no `OutputName` value was provided, `value` contains a feature collection. Use dark colors for code blocksCopy `1 2 3 4 5 { "paramName":"output", "dataType":"GPString", "value":{"layerDefinition": {}, "featureSet": {} } }` See Feature output for more information about how the result layer or collection is accessed.

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:

Use dark colors for code blocksCopy
[{"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:

Use dark colors for code blocksCopy
{"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.

Use dark colors for code blocksCopy
{
 "paramName":"output",
 "dataType":"GPString",
 "value":{"url":"<hosted featureservice layer url>"}
}

If no OutputName value was provided, value contains a feature collection.

Use dark colors for code blocksCopy
{
"paramName":"output",
"dataType":"GPString",
"value":{"layerDefinition": {}, "featureSet": {}  }
}

See Feature output for more information about how the result layer or collection is accessed.