Skip to main content

Statistics API

Statistics API provides information about statistical computations (such as average, standard deviation, etc) on optical imagery data for an area of interest (AOI) across given band math expression and time ranges.

Extract valuable insights from satellite imagery using advanced statistical methods such as average, standard deviation, and more. With our Statistics API, you can choose from 17 default indices (NDVI, RECI, MSAVI, etc.) or create custom band combinations to derive meaningful information for your use cases. Additionally, it gives you access to accurate soil moisture data obtained by our proprietary algorithm.

It’s based on HTTP requests sent to the server, the response format is JSON.

Statistics API workflow contains of two steps:

Rate per minute

Both endpoints in the Statistics API (Task creation and Task status checking) have the "rate limit", currently it is 10 requests per minute for each endpoint in the context of your api_key. Please check this example to find a possible way of implementing access to this API respecting mentioned limits.

Task creation​

This API endpoint allows you to create a new task for statistical computations and returns your task identifier.

HTTP Request​

POST 'https://api-connect.eos.com/api/gdw/api?api_key=<your_api_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"type":"mt_stats",
"callback_url":"callback_url",
"params": {
"bm_type":["index_name"],
"date_start":"date_start",
"date_end":"date_end",
"geometry":
{
"type": "Polygon",
"coordinates": [
[ [lon,lat],
[lon,lat],
.........,
[lon,lat],
[lon,lat],
]
]
},
"reference":"reference_id",
"sensors":["satellite name1"],
"max_cloud_cover_in_aoi":"number",
"exclude_cover_pixels":"true",
"cloud_masking_level":"number"
}
}

Request Parameters​

Request Path ParameterDescription
api_key(Required) Apikey retrieved from developer portal
Request Body ParameterDescription
type(required) Operation name. Value is 'mt_stats'.
params(required) Request parameters.
callback_url(optional) Callback URL. It is used to receive asynchronous responses from the API server, allowing for non-blocking or asynchronous communication between the server and the client application.
params.date_start(required) Start of a time range from which to retrieve the images. The service computes statistics for each image from the time range that fits the prescribed criteria.
params.date_end(required) End of a time range from which to retrieve the images.
params.bm_type(required)
Use for this parameter one of the values or an alias or one expression or an array of band math expressions based on which the statistics are computed.
For the list of supported band math expressions please refer to Supported Bands

Use 'soilmoisture' value for this parameter to obtain soil moisture statistics (soil moisture contains some restrictions*).
params.sensors(required)
Use for this parameter one or more values from the list of sensor names (it's the value of dataset_id from Supported Datasets)

Use 'soilmoisture' value for this parameter to obtain soil moisture (soil moisture contains some restrictions*).
params.reference(required) Unique id to assign to the request.
params.geometry(required) A GeoJSON representation of a geometry describing the AOI. Supported geometry types: "Polygon".

NOTE!: when you add coordinates in the first place - longitude and in the second - latitude.
params.limit(optional) Number of scenes based on which the statistics are computed; by default 100
params.max_cloud_cover_in_aoi(optional) filter scenes by upper threshold for cloud coverage percentage; by default 0
params.exclude_cover_pixels(optional, only for S2) boolean, enable/disable cloud masking using MSK_CLOUDS_B00.gml for statistics calculation; by default - true
params.cloud_masking_level(optional, integer, only for S2) enable advanced cloud masking for Sentinel-2 using SCL band of product L2A.
Valid values:
1. (high probability clouds),
2. (medium + high probability clouds),
3. (medium + high probability + thin cirrus clouds)

By default - null (advanced cloud masking is disabled)

Note, that we added the ability to receive data on callback url. When making a request to an API, you might include a callback URL as part of the request parameters. This URL is where the API server will send results when they become available. Once the API server processes the request or completes a specific task, it sends the result to the callback URL via an HTTP request.

HTTP Response​

{
"status": "created",
"task_id": "string_with_task_id",
"req_id": "string_with_req_id",
"task_timeout":"number"
}

Response parameters​

ParameterDescription
statuscurrent task status (available statuses: "created", "started", "finished"). The default value is "created".
task_idtask identifier
req_idreq identifier
task_timeout(number) task lifetime in seconds

Task status​

HTTP Request​

GET https://api-connect.eos.com/api/gdw/api/<task_id>?api_key=<your api key>

Request Parameters​

ParameterDescription
api_key(Required) Apikey retrieved from developer portal
task_id(Required) Task identifier retrieved from POST request

HTTP Response​

{
"errors": [
{
"scene_id": "string",
"view_id": "string",
"date": "date",
"error": "string",
"notes": ["string"]
},
{..........}
],
"result": [
{
"scene_id": "string",
"view_id": "string",
"date": "date",
"cloud": "number",
"notes": ["string"],
"q1": "number",
"q3": "number",
"max": "number",
"min": "number",
"p10": "number",
"p90": "number",
"std": "number",
"median": "number",
"average": "number",
"variance": "number",
"ctime10": "number"
},
{..........}
]
}

Response parameters​

ParameterDescription
errors.scene_idscene identifier
errors.view_idthe view id of the scene
errors.dateacquisition date
errors.errorerror message
errors.notessome description
result.scene_idscene identifier
result.view_idthe view id of the scene
result.dateacquisition date
result.cloudthe percent of clouds in the scene within the AOI
result.notessome description
result.q1the first quantile of the scene within the AOI. The first quartile of vegetation index can provide valuable information about the lower range of vegetation index values for that region. It is a useful measure of spread or variability that can help to characterize the distribution of vegetation index values within the AOI.
result.q3the third quantile of the scene within the AOI
result.maxthe maximum of the scene within the AOI
result.minthe minimum of the scene within the AOI
result.p10the 10th percentile of the scene within the AOI.
The 10th percentile of the vegetation index value is a statistical measure that represents the value below which 10% of the observed values fall. In other words, it is the vegetation index value that is smaller than 90% of the other values.
result.p90the 90th percentile of the scene within AOI.
The 90th percentile of vegetation index value is a statistical measure that represents the value below which 90% of the observed vegetation index values fall. In other words, it is the vegetation index value that is greater than 90% of the other values.
result.stdthe standard deviation of the scene within the AOI.
The standard deviation of vegetation index values within a specific AOI (Area of Interest) is a statistical measure that represents the degree of variability in the vegetation index data. A higher standard deviation indicates that the vegetation index values are more spread out and less consistent, while a lower standard deviation suggests that the vegetation index values are more tightly clustered around the mean value.
result.medianthe second quartile (median) of the scene within the AOI.
The second quartile (median) can provide valuable information about that region's typical or representative vegetation index value. It is a useful measure of central tendency that is less affected by extreme values compared to other measures such as the mean.
result.averagethe average of the scene within the AOI
for soil moisture - the average value on the surface ("surface soil moisture")
The average value can provide valuable information about that region's typical or representative vegetation index value. It is a useful measure of central tendency that can help to characterize the overall vegetation conditions within the AOI. However, it is important to note that the average vegetation index value may not capture the spatial variability in vegetation cover and density within the AOI, which can be better characterized by measures such as the standard deviation or variance of the vegetation index values.
result.variancethe variance of the scene within the AOI
The variance of vegetation index values can provide valuable information about the spread or variability of vegetation index values within that region. Areas with a high variance of vegetation index values may indicate spatial heterogeneity in vegetation cover and density, while areas with a low variance of vegetation index values may indicate relatively homogeneous vegetation conditions.
result.ctime10available only soil moisture and contains value "root zone soil moisture"

NOTE!: With exclude_cover_pixels option enabled, results may contain null values in cases when all data pixels are discarded as cloudy.

Cloud Masking Options​

There is an option to exclude cloud pixels during statistics calculation for Sentinel-2 via parameters exclude_cover_pixels and cloud_masking_level.

When exclude_cover_pixels option is enabled, then cloud masks are used, which are provided along with Sentinel-2 L1C product hosted on AWS S3.

These GML masks feature two types of clouds: "OPAQUE" and "CIRRUS". Only "OPAQUE" clouds are masked in statistics calculation.

When cloud_masking_level option is enabled, then cloud masks are built from SCL band of Sentinel-2 L2A if L2A product is available. For documentation on SCL band please refer to Classification Mask Generation. Possible values of cloud_masking_level:

1 - mask high probability clouds

2 - mask medium + high probability clouds

3 - mask medium + high probability + thin cirrus clouds

The best results are achieved when combining both SCL and GML cloud masks during statistics calculation.

The Scene Classification (SCL) algorithm allows the detection of clouds, snow and cloud shadows and generation of a classification map, which consists of three different classes for clouds (including cirrus), together with six different classifications for shadows, cloud shadows, vegetation, not vegetated, water and snow. Cloud screening is applied to the data in order to retrieve accurate atmospheric and surface parameters during the atmospheric correction step. The L2A SCL map can also be a valuable input for further processing steps or data analysis.

The SCL algorithm uses the reflective properties of scene features to establish the presence or absence of clouds in a scene. It is based on a series of threshold tests that use as input: TOA reflectance of several SENTINEL-2 spectral bands, band ratios and indexes like Normalised Difference Vegetation Index (NDVI) and Normalised Difference Snow and Ice Index (NDSI). For each of these threshold tests, a level of confidence is associated. It produces at the end of the processing chain a probabilistic cloud mask quality indicator and a snow mask quality indicator. The most recent version of the SCL algorithm includes also morphological operations, usage of auxiliary data like Digital Elevation Model and Land Cover information and exploit the parallax characteristics of SentinelSENTINEL-2 MSI instrument to improve its overall classification accuracy.