Join features

A join analysis resulting in a new layer that contains an additional field for average home value within census blocks.

What is a join analysis?

A join analysis is the process of combining the attributes from one feature dataset to another based on spatial and/or attribute relationships. The join data can be a feature layer or table. To execute the analysis, use the spatial analysis service and the JoinFeatures operation.

When features are joined, you can use the attributes to calculate statistics, classify the data, show additional data in popups, or visualize the data using renderers.

Real-world examples of this analysis include the following:

Joining a table of flood data to a feature layer of county boundaries to visualize affected counties.
Joining the attributes of a land use data with zoning data to see discrepancies between zoning and use for each parcel.
Combining valve inspection records to fire hydrant locations to determine which hydrants are due for inspection.

How to perform a join analysis

Review the parameters for the JoinFeatures operation.
Send a request to get the spatial analysis service URL.
Execute a job request with the following URL and parameters:
- URL: https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/submitJob
- Parameters:
  - inputLayer: The point, line, polygon, or table hosted feature layer that will have attributes from the joinLayer parameter appended to its table.
  - joinLayer: The point, line, polygon, or table hosted feature layer that will be joined to the targetLayer parameter.
  - 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.
  - outputName: A string representing the name of the hosted feature layer to return with the results.
Check the status.
Get the output layer results.

To see examples using ArcGIS API for Python, ArcGIS REST JS, and the ArcGIS REST API, go to Examples below.

URL request

Use dark colors for code blocksCopy
http://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/SubmitJob?<parameters>

Required parameters

Name	Description	Examples
`f`	The format of the data returned	`f=json` `f=pjson`
`token`	An OAuth 2.0 access token.	`token=<ACCESS_TOKEN>`
`targetLayer`	The point, line, polygon, or table layer that will have attributes from the `joinLayer` parameter appended to its table.	`{"url": <SERVICE_URL>, "filter": <where clause>}`
`joinLayer`	The point, line, polygon, or table layer that will be joined to the `targetLayer` parameter.	`{"url": <SERVICE_URL>, "filter": <where clause>}`

Key parameters

Name	Description	Examples
`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.	`[{"targetField":"county","operator":"equal","joinField":"Area_Name"}]`
`joinOperation`	A string representing the type of join (JoinOneToOne or JoinOneToMany) that will be applied.	`"joinType":"inner"`
`outputName`	A string representing the name of the hosted feature layer to return with the results. NOTE: If you do not include this parameter, the results are returned as a feature collection (JSON).	`{"serviceProperties": {"name": "<SERVICE_NAME>"}}`

Code examples

Join attributes from a table

This example uses the JoinFeatures operation to visualize counties with the highest recreation acreages. A feature table of recreation area values is joined to a polygon hosted feature layer by matching the Area_Name field values present in both feature layers.

In the analysis, the targetLayer value is the North Carolina regions hosted feature layer. The joinLayer value is the North Carolina resources table. The attributes of the joinLayer are appended to the targetLayer based on the values provided in the attributeRelationship parameter.

Join analysis joining a state recreation area table to polygon regions in North Carolina.

APIs

ArcGIS API for Python

ArcGIS REST JS

Expand

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
targetLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/nc_regions/FeatureServer/0"

joinLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/nc_resource_table/FeatureServer/0"

results = join_features(
    target_layer=targetLayer,
    join_layer=joinLayer,
    join_operation="joinOneToOne",
    attribute_relationship=[
        {
            "targetField": "county",
            "operator": "equal",
            "joinField": "Area_Name",
        }
    ],
    # Outputs results as a hosted feature layer.
    output_name="Join features results",
)

print(f"New item created : {results.itemid}")

Go to tutorial

Service requests

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "helperServices": {
    // Other parameters
    "analysis": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
  }
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/submitJob HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>
&targetLayer={"url":"https://services.arcgis.com/P3ePLMYs2RVChkJx/arcgis/rest/services/USA_Counties_Generalized/FeatureServer/0","filter":"STATE_NAME = 'North Carolina'","name":"County Polygons"}
&joinLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/environment_recreation_and_resources_linc/FeatureServer/0","filter":"(Area_Type = 'County') AND (Year = 2022)","name":"Environment-Recreation-Resources"}
&joinOperation=joinOneToOne
&attributeRelationship=["{"targetField":"NAME","operator":"equal","joinField":"Area_Name"}"]
&recordsToMatch={"groupByFields":"","orderByFields":"ObjectId ASC","topCount":1}
&joinType=inner
&outputName={"serviceProperties":{"name":"Join features sql result"}}
&context={"extent":{"xmin":-9745081.305501556,"ymin":3688856.7703679274,"xmax":-7938721.45306675,"ymax":4734515.317308861,"spatialReference":{"wkid":102100,"latestWkid":3857}}}

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy

{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSubmitted",
  "results": {},
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/jobs/j347a8b21b5d943fbb4600772f3b2043e HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Expand
Use dark colors for code blocksCopy
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "outputLayer": {
      "paramUrl": "results/outputLayer"
    }
  },
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/jobs/j347a8b21b5d943fbb4600772f3b2043e/results/outputLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "paramName": "outputLayer",
  "dataType": "GPString",
  "value": {
      "url": "<RESULT_ITEM_URL>",
      "itemId": "<RESULT_ITEM_ID>"
  }
}

Join attributes from a feature layer

This example uses the JoinFeatures operation to join home value data to census blocks. The attributes of the points that intersect with the polygons are joined, allowing you to visualize the census blocks by the average home value (AVGVAL_CY) field.

In the analysis, the targetLayer value is the Census Blocks hosted feature layer. The joinLayer is the San Francisco housing data hosted feature layer. The spatialRelationship parameter is set to intersects.

Join analysis joining average home values from a census centroid layer to census blocks in San Francisco.

APIs

ArcGIS API for Python

ArcGIS REST JS

Expand

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
targetLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Census_blocks_within_San_Francisco/FeatureServer/0"

joinLayer = {
    "url": "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Centroids_for_San_Francisco_housing/FeatureServer/0",
    "filter": "AVGVAL_CY > 0",
}

results = join_features(
    target_layer=targetLayer,
    join_layer=joinLayer,
    join_operation="joinOneToOne",
    join_type="inner",
    spatial_relationship="intersects",
    # Outputs results as a hosted feature layer.
    output_name="Join features results",
)

print(f"New item created : {results.itemid}")

Go to tutorial

Service requests

Request

HTTP

cURL

Use dark colors for code blocksCopy
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "helperServices": {
    // Other parameters
    "analysis": {
      "url": "https://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer"
    },
    "geoenrichment": {
      "url": "https://geoenrich.arcgis.com/arcgis/rest/services/World/GeoenrichmentServer"
    }
  }
}

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
POST /arcgis/rest/services/tasks/GPServer/JoinFeatures/submitJob HTTP/1.1
Host: analysis3.arcgis.com

f=json
&token=<ACCESS_TOKEN
&targetLayer=%7B%22url%22%3A%22https%3A%2F%2Fservices3.arcgis.com%2FGVgbJbqm8hXASVYi%2Farcgis%2Frest%2Fservices%2FCensus_blocks_within_San_Francisco%2FFeatureServer%2F0%22%7D
&joinLayer=%7B%22url%22%3A%22https%3A%2F%2Fservices3.arcgis.com%2FGVgbJbqm8hXASVYi%2Farcgis%2Frest%2Fservices%2FCentroids_for_San_Francisco_housing%2FFeatureServer%2F0%22%2C%20%22filter%22%3A%22AVGVAL_CY%20%3E%200%22%7D
&joinOperation=joinOneToOne
&joinType=inner
&spatialRelationship=intersects
&outputName={"serviceProperties":{"name":"Join features spatial result"}}

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy

{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSubmitted",
  "results": {},
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/jobs/j347a8b21b5d943fbb4600772f3b2043e HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Expand
Use dark colors for code blocksCopy
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "outputLayer": {
      "paramUrl": "results/outputLayer"
    }
  },
  "inputs": {},
  "messages": []
}
Expand

Request

HTTP

cURL

Use dark colors for code blocks

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
POST <ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/JoinFeatures/jobs/j347a8b21b5d943fbb4600772f3b2043e/results/outputLayer HTTP/1.1
Content-Type: application/x-www-form-urlencoded

f=json
&token=<ACCESS_TOKEN>

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy
{
  "paramName": "outputLayer",
  "dataType": "GPString",
  "value": {
      "url": "<RESULT_ITEM_URL>",
      "itemId": "<RESULT_ITEM_ID>"
  }
}