- URL:https://<geoanalytics-url>/SummarizeWithin
- Version Introduced:10.5
Description
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
Parameter | Details |
---|---|
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:
REST examples
|
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. At 10.5.1, 10.6, and 10.6.1, if a projected coordinate system is not specified when running the analysis, the World Cylindrical Equal Area (WKID 54034) projection will be used. At 10.7 or later, 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. Values: Hexagon | Square (default) Note:Either a binType or sumWithinLayer value must be specified. If a binType value is specified, binSize and binSizeUnit values must be specified as well. REST examples
|
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
|
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
|
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:
REST examples
|
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:
REST examples |
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:
REST examples |
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
|
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
|
groupByField (Optional) | Introduced at 10.6.1. 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
|
minorityMajority (Optional) | Introduced at 10.6.1. 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) | Introduced at 10.6.1. 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
|
context (Optional) | The context parameter contains additional settings that affect task execution. For this task, there are four settings:
|
f | The response format. The default response format is html. Values: html | json |
Example usage
The following is a sample request URL for SummarizeWithin:
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.
{
"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:
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:
https://<analysis-url>/SummarizeWithin/jobs/<jobId>/results/<response type>?token=<your token>&f=json
Response | Description |
---|---|
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.
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. 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.
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.
|