Statistical API

The Statistical API is in beta release. It might misbehave in case of large requests. We may change the interface, although no major changes are expected. If you have suggestions for improvements or any feedback, please share your thoughts on our forum.

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 familiarise yourself with the Statistical API, we recommend checking the Requests builder and our API reference.

The Statistical API fully replaces the FIS service and brings additional functionality described below. It is currently available only at the main Sentinel Hub deployments at eu-central-1 and us-west-2 regions. Use the FIS service to get statistics for Sentinel-3 and Sentinel-5P.

General approach

Based on parameters specified by users in requests (e.g. area of interest, time range, evalscript) the Statistical API processes satellite data in a similar way as Process API. Instead of returning images, it calculates requested statistics and returns the results in a json format.

Statistical API and evalscript

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 output, always return also dataMask output. This output defines which pixels are excluded from calculations. For more details and an example, see here.
• The default value of sampleType is FLOAT32.
• The output.bands parameter in the setup() function can be an array. This makes it possible to specify custom names for the output bands and different output dataMask for different outputs, see this example.

API's features

Split 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:

...
"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 (e.g. "P5D", "P30D"). You can only use period OR time designator not both.

If a timeRange is not divisible by an aggregationInterval, the last ("not full") time interval will be dismissed.

Note that 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. If you use mosaicking SIMPLE, one mosaicked output for each time interval is a basis for calculating statistics.

Histogram

Requesting histograms is optional. A variety of histogram customisations are available. Users can specify:

• number of bins nBins or
• width of bins binWidthor
• arbitrary bins.

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% percentile, add the "percentiles" parameter to your requests as:

...
{
  "percentiles": {
    "k": [33, 75, 90]
  }
}
...

See also this example.

Exclude pixels from calculations (dataMask output)

It is possible to exclude certain 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 value "0" for the pixels, which should be excluded from the calculations, and a value of "1" elsewhere for all others. The values of the "dataMask" output are defined by the user in an evalscript. An illustrative example is excluding water pixels from statistics of NDVI, see this example.

Multiple outputs and multi bands 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 this.

Examples

Examples of Statistical API