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 downloading any images. In your Statistical API request, you can specify your area of interest, time period, evalscript and which statistical measures you require. The requested statistics will be returned in the API response. Using Statistical API one can calculate percentage of cloudy pixels for given area of interest and time period or calculate mean, standard deviation and histogram of band values for a parcel in given time period. Find more examples here.

To get familiar with the Statistical API, we recommend checking the Requests builder and our API reference.

The Statistical API fully replaces FIS service and brings additional features described below.

General approach

Based on parameters specified by users in requests (e.g. area of interest, time range, evalscript) Statistical API processes satellite data in a similar manner as Process API. Instead of returning images, it then calculates different statistics and returns 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 Statistical API:

• evaluatePixel() function must besides other outputs always return also dataMask output, which defines which pixels will be excluded from calculations. For more details and an example see here.
• The default value of sampleType is FLOAT32.
• output.bands parameter in setup() function can be an array. This enables specifying custom names for output bands and different output dataMask for different outputs, see this example

API's features

Split requested timeRange into multiple time intervals

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"
},
...

will return the requested statistics calculated for multiple 10-day intervals, see this example. Aggregation intervals can be:

• days (e.g. "P5D", "P30D") or
• hours (e.g. "PT12h").

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

It is important to note that statistics is not automatically calculated for many acquisitions in time. To calculate statistics over time (e.g. max NDVI value in a month), one needs to set mosaicking to ORBIT or TILE and do the calculation in an evalscript, see this example. If you use mosaicking SIMPLE, then one mosaicked output for each time interval is a basis for calculating statistics.

Histogram

Requesting histograms is optional. Variety of histogram customisation is 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 "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 shall have value "0" for the pixels, which shall be excluded from the calculations and value "1" elsewhere. The values of the "dataMask" output are defined by user in an evalscript. One 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 shows how to do all of these.

Examples

Examples of Statistical API