ArcGIS REST API - ArcGIS Services - Summarize Raster Within

URL:https://<rasteranalysistools-url>/SummarizeRasterWithin
Related Resources:Add Image, Calculate Density, Calculate Distance, Calculate Travel Cost, Classify, Classify Pixels Using Deep Learning, Convert Feature to Raster, Convert Raster to Feature, Copy Raster, Create Image Collection, Create Viewshed, Delete Image, Delete Image Collection, Detect Objects Using Deep Learning, Determine Optimum Travel Cost Network, Determine Travel Cost Paths to Destinations, Determine Travel Cost Path as Polyline, Export Training Data for Deep Learning, Fill, Flow Accumulation, Flow Direction, Flow Distance, Generate Raster, Install Deep Learning Model, Interpolate Points, List Deep Learning Model Info, Nibble, Query Deep Learning Model Info, Segment, Stream Link, Train Classifier, Uninstall Deep Learning Model, Watershed
Version Introduced:10.5

Description

Summarize Raster Within diagram

The Summarize Raster Within task summarizes the cells of a raster within the boundaries of areas defined by another dataset.

You can think of SummarizeRasterWithin as taking two layers, one that defines specific areas and another that defines the value of each location across the whole area, and calculating some summary statistic for all of the values that fall within each particular area. The layer that defines the areas, inputZoneLayer, is a feature or raster dataset that defines the boundaries of each of the areas (zones) for which a summary values will be calculated. The area defining the values, the inputRasterLayertoSummarize, is a raster dataset recording the value of some particular property at each location.

The statistic can report such properties as the sum of all the values in each area, the maximum value, or the average value. The statisticType can be calculated based on some mathematical function, the result of a sorting operation on the values, or an indication of the frequency values.

Some example applications of SummarizeRasterWithin include:

Calculating the total acreage of land-use type for each watershed when given a layer of watershed boundaries and a layer of land-use boundaries by land-use type.
Summarizing the average value of vacant parcels within each city boundary when given a layer of parcels in a county and a layer of city boundaries.

Request parameters


Parameter	Details
inputZoneLayer (Required)	The layer the defines the boundaries of the areas. Syntax: This parameter can have either a raster input or a feature input. For raster input, this parameter can be specified as a Portal Item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset. For feature input, this parameter can be specified as either a URL to a feature service layer or a feature collection. Raster input examples: `//Portal item as input raster "inputZoneLayer":{"itemId": <portal item Id>} //URL as input raster "inputZoneLayer":{"url": <image service layer url>}` Feature input examples: `//Feature layer URL "inputZoneLayer":{"url": <feature service layer url>} //Feature collection "inputZoneLayer":{"layerDefinition": {}, "featureSet": {}}`
zoneField (Required)	A field on the inputZoneLayer that holds the values that define each zone. It can be an integer or a string field of the zone dataset. Example: `"zoneField": "Boundary1"`
inputRasterLayertoSummarize (Required)	Choose the raster layer you wish to summarize by the areas defined by the inputZoneLayer. Syntax: This parameter can be specified as a Portal Item ID, a URL to a raster image service layer, a cloud raster dataset, or a shared raster dataset. Examples: `//Portal item as input raster to summarize "inputRasterLayertoSummarize":{"itmeId": <portal item Id>} //URL as input raster to summarize "inputRasterLayertoSummarize":{"url": <image service layer url>}`
outputName (Required)	The output image service name that will be created. You can specify the name, or you can create an empty service using Portal Admin Sharing API and use the return JSON object as input to this parameter. Syntax: A JSON object describes the name of the output or the output raster. Output name example: `"outputName":{"serviceProperties":{"name":"testrasteranalysis"}}` Output raster examples: `//Output portal item: "outputName":{"itemId": <portal item id>} //Output url: "outputName":{"url": <image service url} //Output raster layer service: "outputName":{"serviceProperties": {"name":"testrasteranalysis", "serviceUrl":"https://<server name>/server/rest/services/Hosted/testrasteranalysis/ImageServer"}, "itemProperties":{"itemId":"8cfbd3ec25584d0d8f4ed23b8ff7c43b","folderId":"sdfwerfbd3ec25584d0d8f4"} }`
statisticType	The statistical summary type that you wish to calculate for all the cells within each zone of the feature in the inputRasterLayertoSummarize. Syntax: The input can be one of the following: Mean: Calculates the average of all cells in the value raster that belongs to the same zone as the output cell. This is the default. Majority: Determines the majority value of all cells in the value raster that belongs to the same zone as the output cell. Maximum: Determines the largest value of all cells in the value raster that belongs to the same zone as the output cell. Median: Finds the median value of all cells in the value raster that belongs to the same zone as the output cell. Minimum: Finds the smallest value of all cells in the value raster that belongs to the same zone as the output cell. Minority: Determines the minority value of all cells in the value raster that belongs to the same zone as the output cell. Range: Finds the range of all cells in the value that belongs to the same zone as the output zone. Sum: Adds the total value of all cells in the value raster that belongs to the same zone as the output cell. STD: Finds the standard deviation of all cells in the value raster that belongs to the same zone as the output cell. Variety: Finds the variety of all cells in the value raster that belong to the same zone as the output cell. If the inputRasterLayertoSummarize is floating-point type, the zonal calculations for Majority, Median, Mean, and Variety cannot be computed. Example: `"statisticType": "Sum"`
ignoreMissingValues	Specify whether missing values in the raster layer to summarize will influence the results of the areas they fall within. Syntax: A Boolean value as either true or false. true specifies that, within any particular area, only cells that have a value in the raster layer being summarized will be used in determining the output value for that area. Any missing or NoData cells will be ignored in the statistics calculations. This is the default. false specifies that, within any particular area, if any cells in the raster layer do not have a value it is deemed that there is insufficient information to perform statistical calculations for all the cells in that zone. As a result, the entire zone will receive the NoData value on the output raster. Example: `"ignoreMissingValues": true`
context	Contains additional settings that affect task execution. This task has the following settings: Extent (extent): A bounding box that defines the analysis area. Output Spatial Reference (outSR): The output raster will be projected into the output spatial reference. Snap Raster (snapRaster): The output raster will have its cells aligned with the specified snap raster. Cell Size (cellSize): The output raster will have the resolution specified by cell size. Mask (mask): Only cells that fall within the analysis mask will be considered in the operation.
f	The response format. The default response format is html. Values: html \| json

Response

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

{
  "jobId": "<unique job identifier>",
  "jobStatus": "<job status>"
}

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

https://<raster analysis tools url>/SummarizeRasterWithin/jobs/<jobId>

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://<raster analysis tools url>/SummarizeRasterWithin/jobs/<jobId>/results/outputRaster

Example usage

Below is a sample request URL for SummarizeRasterWithin.

https://services.myserver.com/arcgis/rest/services/System/RasterAnalysisTools/GPServer/SummarizeRasterWithin/submitJob

JSON response syntax

The response returns the outputRaster output parameter, which has properties for parameter name, data type, and value. The content of value is always the output raster dataset itemId and the image service URL.

{
  "paramName": <parameter name>,
  "dataType": "GPString",
  "value": {
    "itemId": <item Id>,
    "url": <URL>
  }
}

JSON response example

{
  "paramName": "outRaster",
  "dataType": "GPString",
  "value": {
    "itemId": "f121390b85ef419790479fc75b493efd", 
    "url": "https://<server name>/arcgis/rest/services/Hosted/<service name>/ImageServer"
  }
}