Statistical API
The Statistical API enables you to get statistics calculated based on satellite imagery without having to download images. In your Statistical API request, you can specify your area of interest, time period, evalscript and which statistical measures should be calculated. The requested statistics are returned in the API response. Using Statistical API you can calculate the percentage of cloudy pixels for a given area of interest and time period, or calculate mean, standard deviation, and histogram of band values for a parcel in a given time period. Find more examples here.
To become familiar with the Statistical API, check the Requests Builder, and our API reference.
General Approach
Based on parameters specified by users in requests (for example, area of interest, time range, evalscript) the Statistical API processes satellite data in a similar way as the Processing API. Instead of returning images, it calculates requested statistics and returns the results in a json format.
Deployments
Statistical API is available on AWS (2 regions). The API's endpoint depends on the chosen deployment as specified in the following table.
| Deployment | API end-point | Region |
|---|---|---|
| AWS EU (Frankfurt) | https://services.sentinel-hub.com/api/v1/statistics | eu-central-1 |
| AWS US (Oregon) | https://services-uswest2.sentinel-hub.com/api/v1/statistics | us-west-2 |
Statistical API and Evalscripts
All general rules for building evalscripts apply. However, there are some specifics when using evalscripts with the Statistical API:
- The
evaluatePixel()function must, in addition to other outputs, always returndataMaskoutput. This output defines which pixels are excluded from calculations. For more details and an example, see here. - The default value of
sampleTypeisFLOAT32. - The
output.bandsparameter in thesetup()function can be an array. This makes it possible to specify custom names for the output bands and different outputdataMaskfor different outputs. See an example here.
Features
Split the Requested timeRange into Multiple Time Intervals
The Statistical API supports requesting statistics for multiple time intervals with only one request.
For example, requesting the aggregationInterval and timeRange as:
- JSON
...
"timeRange": {
"from": "2020-06-01T00:00:00Z",
"to": "2020-07-31T00:00:00Z"
},
"aggregationInterval": {
"of": "P10D"
}
...
Returns the requested statistics calculated for multiple 10-day intervals, see this example. The aggregation intervals should be at least one day long (for example, "P5D", "P30D"). You can only use a period or a time designator and not both.
If a timeRange is not divisible by an aggregationInterval, the last ("not full") time interval will be dismissed by default (SKIP option).
You can instead set the lastIntervalBehavior to SHORTEN (shortens the last interval so that it ends at the end of the provided time range) or EXTEND (extends the last interval over the end of the provided time range so that all the intervals are of equal duration).
The data is mosaicked for each of the time intervals (as defined with the mosaicking parameter in an evalscript) before the statistics are calculated. To calculate statistics over time (for example, the maximum NDVI value in a month), you should set mosaicking to ORBIT or TILE and calculate the required value in an evalscript, see this example.
While mosaicking SIMPLE can be used to generate a single image per interval, it is not suitable for aggregating statistics over longer time intervals. For short intervals (e.g., daily requests), it may still produce valid results.
Histogram
Requesting histograms is optional, and a variety of histogram customisations are available. You can specify any of the following:
- arbitrary
bins - width of bins
binWidth - number of bins
nBins
Along with binWidth and nBins, you can also provide values for lowEdge and/or highEdge parameters.
Otherwise, their default values will be used, which correspond to min and max statistics for a particular output band.
This example demonstrates all three options.
Percentile Calculations
It is possible to get values for any percentile. For example, to get values for 33%, 75%, and 90% percentiles, add the percentiles parameter to your requests as:
- JSON
...
{
"percentiles": {
"k": [33, 75, 90]
}
}
...
See also this example.
Exclude Pixels from Calculations (dataMask output)
It is possible to exclude specific pixels from the calculation of the statistics. The most common use cases are excluding no data and cloudy pixels.
With the Statistical API, this is achieved by defining a special output called dataMask. This output should have a value of "0" assigned for the pixels that should be excluded from the calculations, and a value of "1" elsewhere. The values of the dataMask output are defined by the user in an evalscript. For an illustrative example of excluding water pixels from statistics of NDVI, see this example.
The Statistical API does not automatically exclude the no data pixels from calculating the statistics. We recommend that you always exclude those unless there is a good reason not to. This is especially important when you are requesting statistics for a polygon, as it will ensure that pixels outside of the polygon (and inside of the bounding box) are excluded. To exclude no data pixels, you need to pass the input dataMask band to the dataMask output. For example:
- javascript
function evaluatePixel(samples) {
return {
...,
dataMask: [samples.dataMask]
}
}
All evalscripts in the examples here exclude no data pixels.
Multiple Outputs and Multi-Band Outputs
Statistics can be requested for multiple outputs. This is useful when we need to use different dataMasks or different sampleTypes for each output. Additionally, each output can have multiple bands. It is possible to request different statistics for each band and for each output. This example demonstrates how to do all of this.