Home > Develop > Documentation > API > Statistical info (FIS) documentation

Statistical info (FIS) documentation

Statistical info API documentation

The Statistical info (or feature info service, abbreviated FIS), performs elementary statistical computations---such as mean, standard deviation, and histogram approximating the distribution of reflectance values---on remotely sensed data for a region specified in a given spatial reference system across different bands and time ranges.

A quintessential usage example would be querying the service for basic statistics and the distribution of NDVI values for a polygon representing an agricultural unit over a time range.

Basic information

The service retrieves all data from the given time range that fit the prescribed criteria, computes statistics on these data, and returns the result in the form of a JSON object.

The base URL for the FIS service: http://services.sentinel-hub.com/ogc/fis/{INSTANCE_ID}. Replace {INSTANCE_ID} with the one you find in the WMS Configurator (as in examples of query URLs at the bottom of the page).

By deafult, the service uses the settings from the instance specified by the instance ID, but one can override these by specifying them in the URL. For example, setting MAXCC=10 overrides whatever is set in the instance settings in the WMS configurator. The instances are managed (i.e., edited, created, and deleted) in the Configuration Utility.

FIS only works on instances that don't enforce image types other than 32 bit RAW. Ensure that the image type is not enforced in the instance configuration (i.e., either have it set to None or to image/raw;depth=32f).

As of this writing, only GET endpoint is implemented.  

More details

More about custom URL parameters, output image formats, atmospheric correction, preview modes, custom evaluation script, and which operations can be used with WMS, WMTS, WFS or WCS services is available here.

 

FIS URL parameters

Below is a list of mandatory FIS parameters. Besides these, one can also pass custom parameters.

Mandatory Parameter Description Example
Yes LAYER The preconfigured layer (image) based on which the statistics are computed. Exactly one layer has to be specified, additional overlays may be added. If the product has multiple bands, such as, for example, LAYER=TRUE_COLOR, statistics are computed for each band separately. See the list of supported EO products. LAYER=NDVI
Yes CRS Coordinate reference system. CRS=EPSG:3857
Yes TIME Time range from which to retrieve the images. The service computes statistics for each image from the time range that fits the prescribed criteria. TIME=2016-01-01/2017-10-30
Yes RESOLUTION Specifies the spatial resolution, in meters per pixel, of the image from which the statistics are to be estimated. When using CRS=EPSG:4326 one has to add the "m" suffix to enforce resolution in meters per pixel (e.g. RESOLUTION=10m). RESOLUTION=10
Yes* GEOMETRY

A WKT representation of a geometry describing the region of interest.

Note that WCS 1.1.1 standard is used here, so for EPSG:4326 coordiantes should be in latitude/longitude order.

GEOMETRY=POLYGON((1795507.58591164 5884963.841868286,1795520.723525876 5885430.824337966,1795740.479982196 5885460.68255214,1795729.731025094 5885202.707581678,1796076.086309511 5885181.209667472,1796059.365709573 5884968.619182554,1795507.58591164 5884963.841868286))
Yes* BBOX A bounding box, represented with the bottom-left and upper-right vertices, describing the region of interest. BBOX=1550369.86,5586056.25,1547498.69,5584861.92
No STYLE Specified style (overrides the one specified in the layer configuration). For indices (one-component products such as NDVI, NDWI, etc.), setting STYLE=INDEX enforces raw data (other popular choices for one-component products include GRAYSCALE and COLORMAP. For multi-component products (such as TRUE_COLOR, FALSE_COLOR, etc.), setting STYLE=SENSOR enforces the raw sensor data to be used, while STYLE=REFLECTANCE enforces raw sensor data scaled to the range [0,1]. See which styles are available for various EO products. STYLE=INDEX
No BINS The number of bins (a positive integer) in the histogram. When this parameter is absent, no histogram is computed. BINS=32

*Note. One should use either BBOX or GEOMETRY, never both, to specify the region of interest.

For more information about layers and styles, see the WMS documentation.

Output format

The service works on single-band (e.g., NDVI, NDWI, etc.) as well as multi-band (e.g., TRUE_COLOR, FALSE_COLOR, etc.) products. In case of a multi-band product, the statistics are computed for each band (see the description of the output structure below).

Results are always returned as JSON objects of the following form:


{
	"bandName1": [
		{
			"date": "date1",
			"basicStats": {
				"min": minValue1,
				"max": maxValue1,
				"mean": meanValue1,
				"stDev": standardDeviation1,
			},
			"histogram": [
				{
					"value": value,
					"count": count
				},
				...,
				{
					"value": value,
					"count": count
				},
			]
		},
		...,
		{
			...
		}
	],
	...,
	"bandNameM": [
		...
	]
}
			

In words, the bands comprising the specified layer correspond to keys in the response JSON object. The value associated with each band is an array of objects containing statistics for that band in the image, one per available date.

The "histogram" is absent when the histogram isn't request (i.e., when the BINS parameter is not set).

Examples

The example below illustrates how data from the statistical service may be visualized.

Visualizing the results

Below is a plot of NDVI value distributions across time ranges. The violin plots were computed from the following FIS request: http://services.sentinel-hub.com/ogc/fis/{INSTANCE_ID}?LAYER=5_VEGETATION_INDEX&STYLE=INDEX&CRS=EPSG%3A3857&TIME=2015-01-01%2F2015-10-01&BBOX=1550369.86,5586056.25,1547498.69,5584861.92&RESOLUTION=10&MAXCC=5&BINS=100

Fis NDVI violins

Requesting stats without a histogram

Query URL: http://services.sentinel-hub.com/ogc/fis/{INSTANCE_ID}?LAYER=5_VEGETATION_INDEX&STYLE=INDEX&CRS=EPSG%3A3857&TIME=2015-01-01%2F2015-10-01&BBOX=1550369.86,5586056.25,1547498.69,5584861.92&RESOLUTION=10&MAXCC=5

Response:


{
  "NDVI": [
    {
      "date": "2015-08-30",
      "basicStats": {
        "min": -0.5478424429893494,
        "max": 0.7815912365913391,
        "mean": 0.147320137875888,
        "stDev": 0.35443419609590726
      }
    },
    {
      "date": "2015-07-11",
      "basicStats": {
        "min": -0.5127978920936584,
        "max": 0.8115044236183167,
        "mean": 0.20168528533031557,
        "stDev": 0.31436594348376923
      }
    }
  ]
}

Requesting stats with a histogram

Query URL: http://services.sentinel-hub.com/ogc/fis/{INSTANCE_ID}?LAYER=5_VEGETATION_INDEX&STYLE=INDEX&CRS=EPSG%3A3857&TIME=2015-01-01%2F2015-10-01&BBOX=1550369.86,5586056.25,1547498.69,5584861.92&RESOLUTION=10&MAXCC=5&BINS=5

Response:


{
  "NDVI": [
    {
      "date": "2015-08-30",
      "basicStats": {
        "min": -0.5478424429893494,
        "max": 0.7815912365913391,
        "mean": 0.147320137875888,
        "stDev": 0.35443419609590726
      },
      "histogram": {
        "bins": [
          {
            "value": -0.23164855383139124,
            "count": 14377.0
          },
          {
            "value": 0.08134964140017291,
            "count": 1844.0
          },
          {
            "value": 0.23792375711536012,
            "count": 4692.0
          },
          {
            "value": 0.37365802377462387,
            "count": 4.0
          },
          {
            "value": 0.5359620948992795,
            "count": 13236.0
          }
        ]
      }
    },
    {
      "date": "2015-07-11",
      "basicStats": {
        "min": -0.5127978920936584,
        "max": 0.8115044236183167,
        "mean": 0.20168528533031557,
        "stDev": 0.31436594348376923
      },
      "histogram": {
        "bins": [
          {
            "value": -0.3067768962218847,
            "count": 145.0
          },
          {
            "value": -0.11833351501876165,
            "count": 14484.0
          },
          {
            "value": 0.13131743694345155,
            "count": 30.0
          },
          {
            "value": 0.24965114950902842,
            "count": 7984.0
          },
          {
            "value": 0.5777060477812307,
            "count": 11510.0
          }
        ]
      }
    }
  ]
}