sentinelhub_statistical

Implementation of Sentinel Hub Statistical API interface

class sentinelhub.sentinelhub_statistical.SentinelHubStatistical(aggregation, input_data, bbox=None, geometry=None, calculations=None, **kwargs)[source]

Bases: sentinelhub.sentinelhub_base_api.SentinelHubBaseApiRequest

Sentinel Hub Statistical API interface

For more information check Statistical API documentation.

For details of certain parameters check the Statistical API reference.

Parameters:
  • aggregation (dict) – Aggregation part of the payload, which can be generated with aggregation method
  • input_data (List[dict or InputDataDict]) – A list of input dictionary objects as described in the API reference. It can be generated with input_data method
  • bbox (sentinelhub.BBox or None) – A bounding box of the request
  • geometry (sentinelhub.Geometry or None) – A geometry of the request
  • calculations – Calculations part of the payload.
  • calculations – dict
  • data_folder (str) – Location of the directory where the downloaded data could be saved.
  • config (SHConfig or None) – A custom instance of config class to override parameters from the saved configuration.
static body(request_bounds, request_data, aggregation, calculations, other_args=None)[source]

Generate the Process API request body

Parameters:
  • request_bounds (dict) – A dictionary as generated by bounds helper method.
  • request_data (List[dict]) – A list of dictionaries as generated by input_data helper method.
  • aggregation (dict) – A dictionary as generated by aggregation helper method.
  • calculations (dict) – A dictionary defining calculations part of the payload
  • other_args – Additional dictionary of arguments. If provided, the resulting dictionary will get updated by it.
  • other_args – dict
Returns:

Request payload dictionary

Return type:

dict

static aggregation(evalscript, time_interval, aggregation_interval, size=None, resolution=None, other_args=None)[source]

Generate the aggregation part of the Statistical API request body

Parameters:
  • evalscript (str) – An evalscript.
  • time_interval ((str, str) or (datetime, datetime)) – An interval with start and end date of the form YYYY-MM-DDThh:mm:ss or YYYY-MM-DD or a datetime object
  • aggregation_interval (str) – How data from given time interval is aggregated together
  • size ((int, int) or None) – A width and height of an image from which data will be aggregated
  • resolution ((float, float) or (int, int) or None) – A resolution in x and y dimensions of an image from which data will be aggregated. Resolution has to be defined in the same units as request bbox or geometry
  • other_args – Additional dictionary of arguments. If provided, the resulting dictionary will get updated by it.
  • other_args – dict
Returns:

Aggregation payload dictionary

Return type:

dict

static bounds(bbox=None, geometry=None, other_args=None)

Generate a bound part of the API request

Parameters:
  • bbox (sentinelhub.BBox) – Bounding box describing the area of interest.
  • geometry (sentinelhub.Geometry) – Geometry describing the area of interest.
  • other_args – Additional dictionary of arguments. If provided, the resulting dictionary will get updated by it.
  • other_args – dict
create_request()

Prepares a download request

get_data(*, save_data=False, redownload=False, data_filter=None, max_threads=None, decode_data=True, raise_download_errors=True)

Get requested data either by downloading it or by reading it from the disk (if it was previously downloaded and saved).

Parameters:
  • save_data (bool) – flag to turn on/off saving of data to disk. Default is False.
  • redownload (bool) – if True, download again the requested data even though it’s already saved to disk. Default is False, do not download if data is already available on disk.
  • data_filter (list(int) or None) – Used to specify which items will be returned by the method and in which order. E.g. with data_filter=[0, 2, -1] the method will return only 1st, 3rd and last item. Default filter is None.
  • max_threads (int or None) – Maximum number of threads to be used for download in parallel. The default is max_threads=None which will use the number of processors on the system multiplied by 5.
  • decode_data (bool) – If True (default) it decodes data (e.g., returns image as an array of numbers); if False it returns binary data.
  • raise_download_errors (bool) – If True any error in download process should be raised as DownloadFailedException. If False failed downloads will only raise warnings and the method will return list with None values in places where the results of failed download requests should be.
Returns:

requested images as numpy arrays, where each array corresponds to a single acquisition and has shape [height, width, channels].

Return type:

list of numpy arrays

get_download_list()

Returns a list of download requests for requested data.

Returns:List of data to be downloaded
Return type:list(sentinelhub.DownloadRequest)
get_filename_list()

Returns a list of file names (or paths relative to data_folder) where the requested data will be saved or read from, if it has already been downloaded and saved.

Returns:A list of filenames
Return type:list(str)
get_url_list()

Returns a list of urls for requested data.

Returns:List of URLs from where data will be downloaded.
Return type:list(str)
static input_data(data_collection, *, identifier=None, time_interval=None, maxcc=None, mosaicking_order=None, upsampling=None, downsampling=None, other_args=None)

Generate the input data part of the request body

Parameters:
  • data_collection (DataCollection) – One of supported Process API data collections.
  • identifier (str or None) – A collection identifier that can be referred to in the evalscript. Parameter is referenced as “id” in service documentation. To learn more check data fusion documentation.
  • time_interval ((str, str) or (datetime, datetime)) – A time interval with start and end date of the form YYYY-MM-DDThh:mm:ss or YYYY-MM-DD or a datetime object
  • maxcc (float or None) – Maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.
  • mosaicking_order (str or None) – Mosaicking order, which has to be either ‘mostRecent’, ‘leastRecent’ or ‘leastCC’.
  • upsampling (str) – A type of upsampling to apply on data
  • downsampling (str) – A type of downsampling to apply on data
  • other_args – Additional dictionary of arguments. If provided, the resulting dictionary will get updated by it.
  • other_args – dict
Returns:

A dictionary-like object that also contains additional attributes

Return type:

InputDataDict

is_valid_request()

Checks if initialized class instance successfully prepared a list of items to download

Returns:True if request is valid and False otherwise
Return type:bool
save_data(*, data_filter=None, redownload=False, max_threads=None, raise_download_errors=False)

Saves data to disk. If redownload=True then the data is redownloaded using max_threads workers.

Parameters:
  • data_filter (list(int) or None) – Used to specify which items will be returned by the method and in which order. E.g. with data_filter=[0, 2, -1] the method will return only 1st, 3rd and last item. Default filter is None.
  • redownload (bool) – data is redownloaded if redownload=True. Default is False
  • max_threads (int or None) – Maximum number of threads to be used for download in parallel. The default is max_threads=None which will use the number of processors on the system multiplied by 5.
  • raise_download_errors (bool) – If True any error in download process should be raised as DownloadFailedException. If False failed downloads will only raise warnings.