Summarize Within

URL:
https://<geoanalytics-url>/SummarizeWithin
Methods:
GET
Version Introduced:
10.5

Description

Summarize Within

The SummarizeWithin operation find features (and portions of features) that are within the boundaries of areas in the first input layer. The following are examples:

  • Given a layer of watershed boundaries and a layer of land-use boundaries, you can calculate the total acreage of land-use type for each watershed.
  • Given a layer of parcels in a county and a layer of city boundaries, you can summarize the average of vacant parcels within each city boundary.
  • Given a layer of counties and a layer of roads, you can summarize the total mileage of roads by road type within each county.

You can think of the SummarizeWithin operation as taking two layers and stacking them on top of each other. One of the layers, the summaryPolygons value, must be a polygon layer, and imagine that these polygon boundaries are colored red. The other layer, the summarizedLayer value, can be any feature type—point, line, or polygon. After stacking these layers on top of each other, you look down through the stack and count the number of features in summarizedLayer that fall within the polygons with the red boundaries (summaryPolygons). Not only can you count the number of features, you can calculate statistics about the attributes of the features in summarizeLayer, such as sum, mean, minimum, maximum, and so on.

Request parameters

ParameterDetails

summaryPolygons (Required if binType is not specified)

The polygon features. Features, or portions of features, in the summarizedLayer value (below) that fall within the boundaries of these polygons will be summarized. You can summarize within a polygon layer that you provide or within a square of hexagon bins that are generated when the tool runs.

Syntax: As described in Feature input, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A URL to a big data catalog service layer with an optional filter to select specific features
  • A feature collection

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"summaryPolygons": {"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

binType (Required if summaryPolygons is not specified)

The type of bin that will be generated and the summarizedLayer value will be summarized into. Analysis using Square or Hexagon bins requires a projected coordinate system. When aggregating layers into bins, the input layer or processing extent (processSR) must have a projected coordinate system. If a projected coordinate system is not specified when running the analysis, a projection that is based on the extent of the data will be used. The default is Square.

Values: Hexagon | Square

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
Hexagon

//REST scripting example
"binType": Square

binSize (Required if binType is specified)

The distance for the binType value. When generating bins, for Square, the number and units specified determine the height and length of the square; for Hexagon, the number and units specified determine the distance between parallel sides.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
108.3

//REST scripting example
"binSize": 100

binSizeUnit (Required if binSize is specified)

The linear distance unit for the bins that the summaryLayer value will be summarized into. The default value is Meters.

Values: Meters | Kilometers | Feet | FeetInt | FeetUS | Miles |MilesInt | MilesUS | NauticalMiles | NauticalMilesInt | NauticalMilesUS | Yards | YardsInt | YardsUS

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
Meters

//REST scripting example
"binSizeUnit": "Miles"

summarizeLayer (Required)

Point, line, or polygon features that will be summarized for each polygon in the summaryPolygons parameter or bins.

Syntax: As described in Feature input, this parameter can be one of the following:

  • A URL to a feature service layer with an optional filter to select specific features
  • A URL to a big data catalog service layer with an optional filter to select specific features
  • A feature collection

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
{"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

//REST scripting example
"summaryPolygons": {"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0", "filter": "Month = 'September'"}

standardSummaryFields (Optional)

A list of field names and statistical summary types you want to calculate. Note that the count is always returned. By default, all statistics are returned.

onStatisticField specifies the name of the fields in the target layer. Numeric fields are assumed to represent a count- or sum-type quantity and will be proportioned prior to calculating statistics if summarizeLayer is a line or polygon layer. In these cases, values are proportioned by the ratio of the length or area of each feature within each summary polygon to the length or area of each feature outside each summary polygon. Numeric fields that represent rate- or index-type quantities should be listed in rateFields and will not proportioned. Field values for point layers are not proportioned regardless of the quantity type. statisticType is one of the following for numeric fields:

  • Count—For numeric fields, this totals the number of values of all the points in each polygon. For string fields, this totals the number of strings for all the points in each polygon.
  • Sum—Adds the total value of all the points in each polygon. It is used for numeric fields.
  • Mean—Calculates the average of all the points in each polygon. It is used for numeric fields.
  • Max—Calculates the largest value of all the points in each polygon. It is used for numeric fields.
  • Range—Finds the difference between the Min and Max values. It is used for numeric fields.
  • Stddev—Finds the standard deviation of all the points in each polygon. It is used for numeric fields.
  • Var—Finds the variance of all the points in each polygon. It is used for numeric fields.
  • Any—Returns a sample string of a point in each polygon. It is used for string fields.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
//REST web example
[{"statisticType": "Mean", "onStatisticField": "Total_Sales"},{"statisticType": "Sum", "onStatisticField": "Total_Sales"}]

//REST scripting example
"summaryFields": [{"statisticType": "Mean", "onStatisticField": "Total_Sales"},{"statisticType": "Sum", "onStatisticField": "Total_Sales"}]

//Only return Count
"summaryFields": []

weightedSummaryFields (Optional)

A list of field names and the statistical summary types that will be calculated for all features in summarizedLayer that are within each polygon in the summaryPolygon parameter or bins. The weighted statistics are calculated by geographically weighting attribute values from features that are within the summaryPolygon value. Resulting fields will be denoted with a p. Weighted statistics can only be applied to the summarizedLayer value that are lines or polygons. onStatisticField specifies the name of the fields in the target layer. Numeric fields are assumed to represent a count- or sum-type quantity and will be proportioned prior to calculating statistics. In this case, values are proportioned by the ratio of the length or area of each feature within each summary polygon to the length or area of each feature outside each summary polygon. Numeric fields that represent rate- or index-type quantities are listed in rateFields and will not proportioned. statisticType can be defined as one of the following:

  • Mean—Calculates the weighted average of all the features in each polygon. This is used for numeric fields.
  • Stddev—Finds the weighted standard deviation of all the features in each polygon. This is used for numeric fields. This option is available at 10.9.1 or later.
  • Var—Finds the weighted variance of all the features in each polygon. This is used for numeric fields. This option is available at 10.9.1 or later.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
[{"statisticType": "Mean", "onStatisticField":"Total_Sales"},{"statisticType":"Stddev", "onStatisticField": "Total_Sales"}]

//REST scripting example
"weightedSummaryFields": [{"statisticType": "Mean", "onStatisticField": "Total_Sales"},{"statisticType": "Stddev", "onStatisticField": "Total_Sales"}]

rateFields (Optional)

A list of numeric fields that represent rate- or index-type quantities. Fields included in this list will not be proportioned prior to calculating standardSummaryFields and weightedSummaryFields values. Fields not included in this list are assumed to represent count or sum quantities and will be proportioned if the features are lines or polygons prior to calculating standardSummaryFields and weightedSummaryFields values. Field values for point features are not proportioned prior to calculating standardSummaryFields and weightedSummaryFields values.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
DivIndex,PopDensity

//REST scripting example
"rateFields": "DivIndex,PopDensity"

sumShape (Optional)

A Boolean value that instructs the task to calculate statistics based on the shape type of the summaryLayer value, such as the length of lines or areas of polygons of summaryLayer within each polygon in sumWithinLayer. The default is true.

Values: true | false

shapeUnits (Optional)

The units used for the sumShape calculation. The available values for this parameter vary depending on the whether the summaryLayer value contains polygons or lines.

If summaryLayer contains polygons, the available values are Acres | AcresInt | AcresUS | Hectares | SquareMeters | SquareKilometers | SquareMiles | SquareMilesInt | SquareMilesUS | SquareYards | SquareYardsInt | SquareYardsUS | SquareFeet | SquareFeetInt | SquareFeetUS

If summaryLayer contains lines, the available values are: Meters | Kilometers | Feet | FeetInt | FeetUS | Yards | YardsInt | YardsUS | Miles | MilesInt | MilesUS | NauticalMiles | NauticalMilesInt | NauticalMilesUS

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
SquareMeters

//REST scripting example
"shapeUnits": "Hectares"

groupByField (Optional)

This is a field of the summarizedLayer features that you can use to calculate statistics separately for each unique attribute value. For example, suppose the sumWithinLayer value contains city boundaries and the summaryPolygons features are parcels. One of the fields of the parcels is Status, which contains two values: VACANT and OCCUPIED. To calculate the total area of vacant and occupied parcels within the boundaries of cities, use Status as the groupByField field. When a groupByField parameter is provided, the service returns a table containing the statistics in the groupBySummary output parameter.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
Status

//REST scripting example
"groupsByField": "Status"

minorityMajority (Optional)

This Boolean parameter is applicable only when a groupByField value is specified. If minorityMajority is set to true, the minority (least dominant) or the majority (most dominant) attribute values for each group field are calculated. Two new fields are added to the resultLayer value prefixed with Majority_ and Minority_. The default value is false.

Values: true | false

percentShape (Optional)

This Boolean parameter is applicable only when a groupByField value is specified. If percentShape is set to true, the percentage of each unique groupByField value is calculated for each sumWithinLayer polygon. The default is false.

Values: true | false

outputName (Required)

The task will create a feature service of the results. You define the name of the service.

REST examples

Use dark colors for code blocksCopy
1
2
3
4
5
//REST web example
myOutput

//REST scripting example
"outputName": "myOutput"

context (Optional)

The context parameter contains additional settings that affect task execution. For this task, there are four settings:

  • Extent (extent )—A bounding box that defines the analysis area. Only those features that intersect the bounding box will be analyzed.
  • Processing spatial reference (processSR )—The features will be projected into this coordinate system for analysis.
  • Output spatial reference (outSR )—The features will be projected into this coordinate system after the analysis to be saved. The output spatial reference for the spatiotemporal big data store is always WGS84.
  • Data store (dataStore )—Results will be saved to the specified data store. The default is the spatiotemporal big data store.

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
5
6
{
  "extent": {extent},
  "processSR": {spatial reference},
  "outSR": {spatial reference},
  "dataStore": {data store}
}

f

The response format. The default response format is html .

Values: html | json | pjson

Example usage

The following is a sample request URL for SummarizeWithin:

Use dark colors for code blocksCopy
1
https://webadaptor.domain.com/server/rest/services/System/GeoAnalyticsTools/GPServer/SummarizeWithin/submitJob?summaryPolygons={"url": "https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/0" "filter":"Month = 'September'"}&binType=Hexagon&binSize=108.3&binSizeUnit=Meters&summarizeLayer={"url":"https://myportal.domain.com/server/rest/services/Hosted/hurricaneTrack/FeatureServer/1" "filter":"City = 'Corpus Christi'"}&sumShape=true&shapeUnits=SquareMeters&outputName=myOutput&f=json

Response

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

Syntax:

Use dark colors for code blocksCopy
1
2
3
4
{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

After the initial request is submitted, you can use jobId to periodically check the status of the job and messages as described in Check job status. Once the job has successfully completed, use jobId to retrieve the results. To track the status, you can make a request of the following form:

Use dark colors for code blocksCopy
1
https://<analysis url>/SummarizeWithin/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
1
https://<analysis-url>/SummarizeWithin/jobs/<jobId>/results/<response type>?token=<your token>&f=json
ResponseDescription

output

The polygon features of summaryPolygon or the bins generated when running the tool with summary statistics and weighted summary statistics about the features in summarizedLayer that fall within each polygon. Proportional statistics fields are denoted with a p.

Use dark colors for code blocksCopy
1
{"url": "https://<analysis-url>/SummarizeWithin/jobs/<jobId>/results/output"}

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. The value contains the URL of the feature service layer.

Use dark colors for code blocksCopy
1
2
3
4
5
{
  "paramName": "output",
  "dataType": "GPRecordSet",
  "value":{"url": "<hosted featureservice layer url>"}
}

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

groupBySummary

If a groupByField field was provided as input, the result will have a groupBySummary table that contains the calculated statistics for each unique group. Tables are a subset of features; that is, they contain attributes but no geometry.

Use dark colors for code blocksCopy
1
{"url": "https://<analysis-url>/SummarizeWithin/jobs/<jobId>/results/groupBySummary"}

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. value contains the URL of the feature service layer.

Use dark colors for code blocksCopy
1
2
3
4
5
{
  "paramName":" groupBySummary",
  "dataType":"GPRecordSet",
  "value":{"url":"<hosted featureservice layer url>"}
}

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