Summarize within

A summarize within analysis resulting in a new layer that contains the total length of bike routes within each district.

What is a summarize within analysis?

A summarize within analysis is the process of finding areas (and portions of areas) that overlap between two feature datasets and calculating statistics for the features that overlap. To execute the analysis, use the spatial analysis service and the SummarizeWithin operation.

Real-world examples of this analysis include the following:

Calculating the total acreage of land-use type features within each polygon of a watershed feature layer.
Summarizing the average value of vacant parcels with each city boundary polygon.
Calculating the total mileage of roads by road type within each county polygon.

How summarize within works

The general steps to performing a summarize within analysis are as follows:

Review the parameters for the SummarizeWithin 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/SummarizeWithin/submitJob
- Parameters:
  - sumWithinLayer: The polygon features. Features, or portions of features, in the summaryLayer that fall within the boundaries of these polygons will be summarized.
  - summaryLayer: The polygon features into which the input points will be aggregated.
  - 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/SummarizeWithin/submitJob?<parameters>

Required parameters

Name	Description	Examples
`f`	The format of the data returned.	`f=json` `f=pjson`
`token`	An access token (API key or OAuth 2.0) with the required Spatial Analysis > Feature analysis privilege.	`token=<ACCESS_TOKEN>`
`sumWithinLayer`	The polygon features. Features, or portions of features, in the `summaryLayer` that fall within the boundaries of these polygons will be summarized.	`{"url": <SERVICE_URL>, "filter": <where clause>}` `{"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}`
`summaryLayer`	Point, line, or polygon features that will be summarized for each polygon in the `sumWithinLayer`.	`{"url": <SERVICE_URL>, "filter": <where clause>}` `{"layerDefinition": {}, "featureSet": {}, "filter": <where clause>}`

Key parameters

Name	Description	Examples
`sumShape`	A Boolean value that instructs the task to calculate statistics based on shape type of the `summaryLayer`, such as the count of points, the total length of lines, or the total area of polygons of the `summaryLayer` within each polygon in the `sumWithinLayer`. If the `summaryLayer` is lines or polygons, the count of features within each summary polygon is returned.	`true` \| `false`
`shapeUnits`	When `summaryLayer` contains polygons: Acres \| Hectares \| SquareMeters \| SquareKilometers \| SquareMiles \| SquareYards \| SquareFeet When `summaryLayer` contains lines: Meters \| Kilometers \| Feet \| Yards \| Miles	`"shapeUnits": "Miles"`
`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>"}}`

Privileges

Example

Calculate the length of bike routes

In this example, the length (in miles) of bike routes is calculated within district polygons. the summaryLayer value is the Bike routes hosted feature layer. The sumWithinLayer value is the Maintenance Assessment District hosted layer containing of polygon features.

The sumShape parameter calculates the count of the line features and the groupByField parameter provides the summarized length of the bike routes within each district.

Summarize within analysis revealing the total length of bike routes in each district.

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
sumWithinLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Summarize_Within/FeatureServer/2"
summaryLayer = "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Summarize_Within/FeatureServer/1"

results = summarize_within(
    summary_layer=summaryLayer,
    sum_within_layer=sumWithinLayer,
    sum_shape=True,
    shape_units="Miles",
    group_by_field="ROUTE",
    minority_majority=False,
    # Outputs results as a hosted feature layer.
    output_name="Summarize within results"
)

print(f"Summarize within result item created {results.itemid}")

Go to API Reference

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

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

f=json
&token=<ACCESS_TOKEN>
&summaryLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Summarize_Within/FeatureServer/1","name":"Bike Routes"}
&sumWithinLayer={"url":"https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Summarize_Within/FeatureServer/2","name":"Maintenance Assessment District"}
&sumShape=true
&shapeUnits=Miles
&groupByField=ROUTE
&minorityMajority=false
&outputName={"serviceProperties":{"name":"Summarize within results"}}

Run in Postman

Response (JSON)

Use dark colors for code blocksCopy

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

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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeWithin/jobs/<JOB_ID> 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
{
  "jobId": "<JOB_ID>",
  "jobStatus": "esriJobSucceeded",
  "results": {
    "resultLayer": {
      "paramUrl": "results/resultLayer"
    },
    "groupBySummary": {
      "paramUrl": "results/groupBySummary"
    }
  },
  "inputs": {},
  "messages": []
}

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
POST <YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeWithin/jobs/<JOB_ID>/results/resultLayer 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": "resultLayer",
  "dataType": "GPString",
  "value":  {
    "url": "<RESULT_ITEM_URL>",
    "itemId": "<RESULT_ITEM_ID>"
}
}