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.

summarize within

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:

  1. Review the parameters for the SummarizeWithin operation.
  2. Send a request to get the spatial analysis service URL.
  3. 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.
  4. Check the status.
  5. 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
1
http://<YOUR_ANALYSIS_SERVICE>/arcgis/rest/services/tasks/GPServer/SummarizeWithin/submitJob?<parameters>

Required parameters

NameDescriptionExamples
fThe format of the data returned.f=json f=pjson
tokenAn OAuth 2.0 access token.token=<ACCESS_TOKEN>
sumWithinLayerThe 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>}
summaryLayerPoint, 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

NameDescriptionExamples
sumShapeA 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
shapeUnitsWhen summaryLayer contains polygons:
Acres | Hectares | SquareMeters | SquareKilometers | SquareMiles | SquareYards | SquareFeet

When summaryLayer contains lines:
Meters | Kilometers | Feet | Yards | Miles
"shapeUnits": "Miles"
outputNameA 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 PythonArcGIS API for PythonArcGIS REST JS
Expand
Use dark colors for code blocksCopy
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}")

Service requests

Request
HTTPHTTPcURL
Use dark colors for code blocksCopy
1
2
3
4
5
POST arcgis.com/sharing/rest/portals/self HTTP/1.1
Content-Type: application/x-www-form-urlencoded

&f=json
&token=<ACCESS_TOKEN>
Response (JSON)
Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
{
  "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"
    }
  }
}

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.