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:
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 Parameter | Description |
|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
| Request Body Parameter | Description |
|---|---|
| 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) |
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
| Parameter | Description |
|---|---|
| status | current task status (available statuses: "created", "started", "finished"). The default value is "created". |
| task_id | task identifier |
| req_id | req 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
| Parameter | Description |
|---|---|
| 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
| Parameter | Description |
|---|---|
| errors.scene_id | scene identifier |
| errors.view_id | the view id of the scene |
| errors.date | acquisition date |
| errors.error | error message |
| errors.notes | some description |
| result.scene_id | scene identifier |
| result.view_id | the view id of the scene |
| result.date | acquisition date |
| result.cloud | the percent of clouds in the scene within the AOI |
| result.notes | some description |
| result.q1 | the 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.q3 | the third quantile of the scene within the AOI |
| result.max | the maximum of the scene within the AOI |
| result.min | the minimum of the scene within the AOI |
| result.p10 | the 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.p90 | the 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.std | the 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.median | the 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.average | the 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.variance | the 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.ctime10 | available only soil moisture and contains value "root zone soil moisture" |
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.