Download Multi-Temporal Statistics

Performs elementary 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.

POST /api?api_key=<API_KEY>
JSON Parameters:
 
  • type – (required) Operation name. Value is ‘mt_stats’.
  • params – (required) Request parameters.
  • 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) One expression or an array of band math expressions based on which the statistics are computed. For list of supported band math expressions please refer to Name Aliases
  • params.sensors – (optional) List of sensor names in Search API format (or Antarctica format). Supported sensors: “sentinel2” (“S2”), “landsat8” (“L8”), “landsat4tm” (“L4TM”), “landsat4mss” (“L4MSS”), “landsat5tm” (“L5TM”), “landsat5mss” (“L5MSS”), “cbers4mux” (“CBERS4MUX”), “cbers4awfi” (“CBERS4AWFI”), “cbers4pan10m” (“CBERS4PAN10M”), “modis” (“MODIS”). Default: [“landsat8”, “sentinel2”, “landsat4tm”, “landsat4mss”, “landsat5tm”, “landsat5mss”, “cbers4mux”, “cbers4awfi”, “cbers4pan10m”].
  • params.reference – (required) Unique id to assign to the request.
  • params.geometry – (required; either geometry or cropper_ref must be set) A GeoJSON representation of a geometry describing the AOI. Supported geometry types: “Polygon”.
  • params.cropper_ref – (required; either geometry or cropper_ref must be set) A resourse id of a GeoJSON representation of a geometry saved into data base using Cropper API
  • params.limit – (optional) Number of scenes based on which the statistics are computed. Deafult is 100
Query Parameters:
 
  • api_key – (required) user’s API key
Response JSON Object:
 
  • type (string) – Operation name. Value is ‘mt_stats’
  • reference (string) – Unique id to assign to the request
  • token (string) – User’s AUTH token
  • result_url (string) – null
  • result (array) – List of results
  • result.errors (object) – List of errors. Each item in list is object that contains “status”, “date”, “scene_id”, “error”
  • result.result (array) – List of successful results. Each result contains list of metrics, “date”, “scene_id”, “view_id” cloud coverage
  • result.result.view_id (number) – the view id of the scene
  • result.result.date (number) – acquisition date
  • result.result.std (number) – the standard deviation of the array
  • result.result.q1 (number) – the first quantile of the array
  • result.result.median (number) – the second quantile of the array (median)
  • result.result.q3 (number) – the third quantile of the array
  • result.result.p10 (number) – the 10th percentile of the array
  • result.result.p90 (number) – the 90th percentile of the array
  • result.result.min (number) – the minimum of the array
  • result.result.max (number) – the maximum of the array
  • result.result.average (number) – the average of the array
  • result.result.variance (number) – the variance of the array
  • result.result.cloud_cover (number) – the percent of clouds in the array
  • client_id (number) – User’s AUTH id
  • task_type (string) – “finish” or “error”
  • hash_id (string) – null
  • error_status – Error status (see Error Codes)
  • error_message – Error message

Examples

NDVI Landsat 8. One spectral index

Example request:

http

POST /api?api_key=XXX HTTP/1.1
Host: gdw.eos.com
Content-Type: application/json

{
    "type": "mt_stats",
    "params": {
        "date_start": "2018-10-10",
        "date_end": "2018-10-25",
        "bm_type": "NDVI",
        "sensors": ["landsat8", "sentinel2"],
        "reference": "ref_1539359837",
        "geometry": {
            "type": "Polygon",
            "coordinates": [
                [
                    [-73.90451431274414,
                        40.55849868512597
                    ],
                    [-73.90451431274414,
                        40.559215982710555
                    ],
                    [-73.90350580215454,
                        40.559215982710555
                    ],
                    [-73.90350580215454,
                        40.55849868512597
                    ],
                    [-73.90451431274414,
                        40.55849868512597
                    ]
                ]
            ]
        }
    }
}

curl

curl -i -X POST 'https://gdw.eos.com/api?api_key=XXX' -H 'Content-Type: application/json' --data-raw '{"params": {"bm_type": "NDVI", "date_end": "2018-10-25", "date_start": "2018-10-10", "geometry": {"coordinates": [[[-73.90451431274414, 40.55849868512597], [-73.90451431274414, 40.559215982710555], [-73.90350580215454, 40.559215982710555], [-73.90350580215454, 40.55849868512597], [-73.90451431274414, 40.55849868512597]]], "type": "Polygon"}, "reference": "ref_1539359837", "sensors": ["landsat8", "sentinel2"]}, "type": "mt_stats"}'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "task_type": "finish",
    "reference": "ref_1539359837",
    "token": "d5d9ffc3525bfecd63fd8fd097888a575597ebd9",
    "result_url": null,
    "result": {
        "errors": [],
            "result": [{
            "q1": 0.0205063559114933,
            "q3": 0.02711761463433504,
            "min": 0.01099664717912674,
            "p90": 0.029728015884757042,
            "max": 0.04058815538883209,
            "average": 0.023794656071338915,
            "median": 0.02409234829246998,
            "p10": 0.016829398274421693,
            "variance": 2.458548522568638e-05,
            "date": "2018-01-26",
            "view_id": "L8/LC08_L1TP_179026_20180126_20180126_01_RT",
            "scene_id": "LC08_L1TP_179026_20180126_20180126_01_RT",
            "cloud": 0.0
        }, {
            "q1": 0.18435029685497284,
            "q3": 0.20106831938028336,
            "min": -0.05357639864087105,
            "p90": 0.21829643845558175,
            "max": 0.7094192504882812,
            "average": 0.1850922020896449,
            "median": 0.19363175332546234,
            "p10": 0.07619943767786028,
            "variance": 0.00861295855986984,
            "date": "2018-08-13",
            "view_id": "L8/LC08_L1TP_180026_20180813_20180828_01_T1",
            "scene_id": "LC08_L1TP_180026_20180813_20180828_01_T1",
            "cloud": 0.0
        }]
    },
    "client_id": 24,
    "type": "mt_stats",
    "hash_id": null
}

Example error response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "client_id": 123,
    "download_id": 123,
    "error_message": "Invalid request: malformed geometry provided",
    "error_status": "01000"
    "reference": "lv_reference",
    "task_type": "error",
    "token": "xxx",
    "type": "bandmath"
}

Example Sentinel-2 - Several Vegetation Indices. Crop by saved geometry

  1. Save the geometry using Cropper API.

http

POST /api/render/cropper/?api_key=XXX HTTP/1.1
Host: gate.eos.com
Content-Type: application/json

{
    "type": "Feature",
    "properties": {},
    "geometry": {
            "type": "Polygon",
            "coordinates": [
                    [
                            [-101.790776, 39.394385],
                            [-101.790776, 39.401681],
                            [-101.781421, 39.401681],
                            [-101.781421, 39.394385],
                            [-101.790776, 39.394385]
                    ]
            ]
    }
}

curl

curl -i -X POST 'https://gate.eos.com/api/render/cropper/?api_key=XXX' -H 'Content-Type: application/json' --data-raw '{"geometry": {"coordinates": [[[-101.790776, 39.394385], [-101.790776, 39.401681], [-101.781421, 39.401681], [-101.781421, 39.394385], [-101.790776, 39.394385]]], "type": "Polygon"}, "properties": {}, "type": "Feature"}'

If a resource has been created successfully, the server responds with 200 OK:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Content-Type: application/json; charset=UTF-8

{"cropper_ref": "04a44173c52c9aad768ee3f3dc92f16c"}
  1. Request download setting the AOI with a cropper_ref:

http

POST /api?api_key=XXX HTTP/1.1
Host: gdw.eos.com
Content-Type: application/json

{
    "type": "mt_stats",
    "params": {
        "date_start": "2018-10-10",
        "date_end": "2018-10-25",
        "bm_type": ["NDVI", "MSI", "EVI"],
        "sensors": ["sentinel2"],
        "reference": "ref_1539359837",
        "cropper_ref": "04a44173c52c9aad768ee3f3dc92f16c"
    }
}

curl

curl -i -X POST 'https://gdw.eos.com/api?api_key=XXX' -H 'Content-Type: application/json' --data-raw '{"params": {"bm_type": ["NDVI", "MSI", "EVI"], "cropper_ref": "04a44173c52c9aad768ee3f3dc92f16c", "date_end": "2018-10-25", "date_start": "2018-10-10", "reference": "ref_1539359837", "sensors": ["sentinel2"]}, "type": "mt_stats"}'

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "task_type": "finish",
    "reference": "ref_1539359837",
    "token": "d5d9ffc3525bfecd63fd8fd097888a575597ebd9",
    "result_url": null,
    "result":  {
            "errors": [],
            "result": [{
                        "EVI": {
                            "std": 0.02114047726195182,
                            "q1": 0.1687072515487671,
                            "q3": 0.19322848320007324,
                            "min": 0.10111689567565918,
                            "p90": 0.2011897146701813,
                            "max": 0.279803603887558,
                            "average": 0.1798923007999866,
                            "median": 0.18548576533794403,
                            "p10": 0.1465519428253174,
                            "variance": 0.00044691977886310194
                        },
                        "MSI": {
                            "std": 0.1153611223911934,
                            "q1": 1.1786832809448242,
                            "q3": 1.310867965221405,
                            "min": 1.055504560470581,
                            "p90": 1.4407910108566284,
                            "max": 1.6852155923843384,
                            "average": 1.2540306237683914,
                            "median": 1.2003484964370728,
                            "p10": 1.1604782104492188,
                            "variance": 0.0133081885593559
                        },
            "NDVI": {
                        "std": 0.032942535429904496,
                        "q1": 0.2517527639865875,
                        "q3": 0.2913980334997177,
                        "min": 0.1463739275932312,
                        "p90": 0.29945226907730105,
                        "max": 0.3586786985397339,
                        "median": 0.2813607454299927,
                        "p10": 0.21743096113204957,
                        "variance": 0.001085210640550513,
                        "average": 0.269114298408815
                    },
                    "view_id": "S2/13/S/GD/2018/10/13/0",
                    "date": "2018-10-13",
                    "scene_id": "S2B_tile_20181013_13SGD_0",
                    "cloud": 0.0
            }]
    },
    "client_id": 24,
    "type": "mt_stats",
    "hash_id": null
}

Error Codes

Errors for mt_stats are reported within a field error_status.

Code Reason
00001 Invalid limit: limit > DEFAULT_SCENE_LIMIT
00010 Invalid sensors
00011 Invalid date range: date_start > date_end
00100 Invalid request: malformed date
00101 Invalid request: no geometry provided
00110 Invalid request: unsupported geometry type. Valid geometry types: VALID_GEOMETRY_TYPES
00111 Invalid request: geometry is not valid
01000 Invalid request: malformed geometry provided
01001 Invalid bm_type. Only aliases are supported for multiple sensors
01010 Search error
01011 Invalid request: Maximum extent size exceeded. Max area should not exceed: MAX_GEOM_AREA km^2
01100 MTS exception. Failed to calc stats: {}, {}
null Unknown error