data_request

Main module to handle data requests.

class sentinelhub.data_request.DataRequest(*, data_folder=None)[source]

Abstract class for all Sentinel Hub data requests.

Every data request type can write the fetched data to disk and then read it again (and hence avoid the need to download the same data again).

Parameters:data_folder (str) – location of the directory where the fetched data will be saved.
create_request()[source]

An abstract method for logic of creating download requests

get_data(*, save_data=False, data_filter=None, redownload=False, max_threads=None, raise_download_errors=True)[source]

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) – number of threads to use when downloading data; default is max_threads=None which by default uses the number of processors on the system
  • 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()[source]

Returns a list of download requests for requested data.

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

Returns a list of file names where the requested data will be saved or read from, if it was already downloaded and saved.

Returns:List of filenames where downloaded data will be saved.
Return type:list(str)
get_url_list()[source]

Returns a list of urls for requested data.

Returns:List of URLs from where data will be downloaded.
Return type:list(str)
is_valid_request()[source]

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)[source]

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) – number of threads to use when downloading data; default is max_threads=None which by default uses the number of processors on the system
  • raise_download_errors (bool) – If True any error in download process should be raised as DownloadFailedException. If False failed downloads will only raise warnings.
class sentinelhub.data_request.OgcRequest(layer, bbox, *, time='latest', service_type=None, data_source=<DataSource.SENTINEL2_L1C: (<_Source.SENTINEL2: 'Sentinel-2'>, <_ProcessingLevel.L1C: 'L1C'>)>, size_x=None, size_y=None, maxcc=1.0, image_format=<MimeType.PNG: 'png'>, instance_id=None, custom_url_params=None, time_difference=datetime.timedelta(days=-1, seconds=86399), **kwargs)[source]

The base class for OGC-type requests (WMS and WCS) where all common parameters are defined.

Parameters:
  • data_source (constants.DataSource) – Source of requested satellite data. It has to be the same as defined in Sentinel Hub Configurator for the given layer. Default is Sentinel-2 L1C.
  • service_type (constants.ServiceType) – type of OGC service (WMS or WCS)
  • size_x (int or str) – number of pixels in x or resolution in x (i.e. 512 or 10m)
  • size_y (int or str) – number of pixels in x or resolution in y (i.e. 512 or 10m)
  • bbox (geometry.BBox) – Bounding box of the requested image. Coordinates must be in the specified coordinate reference system.
  • time (str or (str, str) or datetime.date or (datetime.date, datetime.date) or datetime.datetime or (datetime.datetime, datetime.datetime)) – time or time range for which to return the results, in ISO8601 format (year-month-date, for example: 2016-01-01, or year-month-dateThours:minuts:seconds format, i.e. 2016-01-01T16:31:21). When a single time is specified the request will return data for that specific date, if it exists. If a time range is specified the result is a list of all scenes between the specified dates conforming to the cloud coverage criteria. Most recent acquisition being first in the list. For the latest acquisition use latest. Examples: latest, '2016-01-01', or ('2016-01-01', ' 2016-01-31')
  • layer (str) – An ID of a layer configured in Sentinel Hub Configurator. It has to be configured for the same instance ID which will be used for this request. Also the satellite source of the layer in Configurator must match the one given by data_source parameter
  • maxcc (float) – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.
  • image_format (constants.MimeType) – format of the returned image by the Sentinel Hub’s WMS getMap service. Default is PNG, but in some cases 32-bit TIFF is required, i.e. if requesting unprocessed raw bands. Default is constants.MimeType.PNG.
  • instance_id (str) – user’s instance id. If None the instance id is taken from the config.json configuration file.
  • custom_url_params (dictionary of CustomUrlParameter enum and its value, i.e. {constants.CustomUrlParam.ATMFILTER:'ATMCOR'}) – dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described at http://www.sentinel-hub.com/develop/documentation/api/custom-url-parameters. Note: in case of constants.CustomUrlParam.EVALSCRIPT the dictionary value must be a string of Javascript code that is not encoded into base64.
  • time_difference (datetime.timedelta) – The time difference below which dates are deemed equal. That is, if for the given set of OGC parameters the images are available at datestimes d1<=d2<=…<=dn then only those with dk-dj>time_difference will be considered. The default time difference is negative (-1s), meaning that all dates are considered by default.
  • data_folder (str) – location of the directory where the fetched data will be saved.
create_request(reset_wfs_iterator=False)[source]

Set download requests

Create a list of DownloadRequests for all Sentinel-2 acquisitions within request’s time interval and acceptable cloud coverage.

Parameters:reset_wfs_iterator (bool) – When re-running the method this flag is used to reset/keep existing wfs_iterator (i.e. instance of WebFeatureService class). If the iterator is not reset you don’t have to repeat a service call but tiles and dates will stay the same.
get_dates()[source]

Get list of dates

List of all available Sentinel-2 acquisitions for given bbox with max cloud coverage and the specified time interval. When a single time is specified the request will return that specific date, if it exists. If a time range is specified the result is a list of all scenes between the specified dates conforming to the cloud coverage criteria. Most recent acquisition being first in the list.

Returns:list of all available Sentinel-2 acquisition times within request’s time interval and acceptable cloud coverage.
Return type:list(datetime.datetime) or [None]
get_tiles()[source]

Returns iterator over info about all satellite tiles used for the OgcRequest

Returns:Iterator of dictionaries containing info about all satellite tiles used in the request. In case of DataSource.DEM it returns None.
Return type:Iterator[dict] or None
class sentinelhub.data_request.WmsRequest(*, width=None, height=None, **kwargs)[source]

Web Map Service request class

Creates an instance of Sentinel Hub WMS (Web Map Service) GetMap request, which provides access to Sentinel-2’s unprocessed bands (B01, B02, …, B08, B8A, …, B12) or processed products such as true color imagery, NDVI, etc. The only difference is that in the case od WMS request the user specifies the desired image size instead of its resolution.

It is required to specify at least one of width and height parameters. If only one of them is specified the the other one will be calculated to best fit the bounding box ratio. If both of them are specified they will be used no matter the bounding box ratio.

Parameters:
  • width (int or None) – width (number of columns) of the returned image (array)
  • height (int or None) – height (number of rows) of the returned image (array)
  • data_source (constants.DataSource) – Source of requested satellite data. It has to be the same as defined in Sentinel Hub Configurator for the given layer. Default is Sentinel-2 L1C.
  • bbox (geometry.BBox) – Bounding box of the requested image. Coordinates must be in the specified coordinate reference system.
  • time (str or (str, str) or datetime.date or (datetime.date, datetime.date) or datetime.datetime or (datetime.datetime, datetime.datetime)) – time or time range for which to return the results, in ISO8601 format (year-month-date, for example: 2016-01-01, or year-month-dateThours:minuts:seconds format, i.e. 2016-01-01T16:31:21). When a single time is specified the request will return data for that specific date, if it exists. If a time range is specified the result is a list of all scenes between the specified dates conforming to the cloud coverage criteria. Most recent acquisition being first in the list. For the latest acquisition use latest. Examples: latest, '2016-01-01', or ('2016-01-01', ' 2016-01-31')
  • layer (str) – An ID of a layer configured in Sentinel Hub Configurator. It has to be configured for the same instance ID which will be used for this request. Also the satellite source of the layer in Configurator must match the one given by data_source parameter
  • maxcc (float) – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.
  • image_format (constants.MimeType) – format of the returned image by the Sentinel Hub’s WMS getMap service. Default is PNG, but in some cases 32-bit TIFF is required, i.e. if requesting unprocessed raw bands. Default is constants.MimeType.PNG.
  • instance_id (str) – User’s Sentinel Hub instance id. If None the instance id is taken from the config.json configuration file.
  • custom_url_params (dictionary of CustomUrlParameter enum and its value, i.e. {constants.CustomUrlParam.ATMFILTER:'ATMCOR'}) – dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described at http://www.sentinel-hub.com/develop/documentation/api/custom-url-parameters. Note: in case of constants.CustomUrlParam.EVALSCRIPT the dictionary value must be a string of Javascript code that is not encoded into base64.
  • time_difference (datetime.timedelta) – The time difference below which dates are deemed equal. That is, if for the given set of OGC parameters the images are available at datestimes d1<=d2<=…<=dn then only those with dk-dj>time_difference will be considered. The default time difference is negative (-1s), meaning that all dates are considered by default.
  • data_folder (str) – location of the directory where the fetched data will be saved.

More info available at: https://www.sentinel-hub.com/develop/documentation/api/ogc_api/wms-parameters

class sentinelhub.data_request.WcsRequest(*, resx='10m', resy='10m', **kwargs)[source]

Web Coverage Service request class

Creates an instance of Sentinel Hub WCS (Web Coverage Service) GetCoverage request, which provides access to Sentinel-2’s unprocessed bands (B01, B02, …, B08, B8A, …, B12) or processed products such as true color imagery, NDVI, etc., as the WMS service. The only difference is that in the case od WCS request the user specifies the desired resolution of the image instead of its size.

More info available at: https://www.sentinel-hub.com/develop/documentation/api/ogc_api/wcs-request

Parameters:
  • resx (str) – resolution in x (resolution of a column) given in meters in the format (examples 10m, 20m, …). Default is 10m, which is the best native resolution of some Sentinel-2 bands.
  • resy (str) – resolution in y (resolution of a row) given in meters in the format (examples 10m, 20m, …). Default is 10m, which is the best native resolution of some Sentinel-2 bands.
  • data_source (constants.DataSource) – Source of requested satellite data. It has to be the same as defined in Sentinel Hub Configurator for the given layer. Default is Sentinel-2 L1C.
  • bbox (geometry.BBox) – Bounding box of the requested image. Coordinates must be in the specified coordinate reference system.
  • time (str or (str, str) or datetime.date or (datetime.date, datetime.date) or datetime.datetime or (datetime.datetime, datetime.datetime)) – time or time range for which to return the results, in ISO8601 format (year-month-date, for example: 2016-01-01, or year-month-dateThours:minuts:seconds format, i.e. 2016-01-01T16:31:21). When a single time is specified the request will return data for that specific date, if it exists. If a time range is specified the result is a list of all scenes between the specified dates conforming to the cloud coverage criteria. Most recent acquisition being first in the list. For the latest acquisition use latest. Examples: latest, '2016-01-01', or ('2016-01-01', ' 2016-01-31')
  • layer (str) – An ID of a layer configured in Sentinel Hub Configurator. It has to be configured for the same instance ID which will be used for this request. Also the satellite source of the layer in Configurator must match the one given by data_source parameter
  • maxcc (float) – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.
  • image_format (constants.MimeType) – format of the returned image by the Sentinel Hub’s WMS getMap service. Default is PNG, but in some cases 32-bit TIFF is required, i.e. if requesting unprocessed raw bands. Default is constants.MimeType.PNG.
  • instance_id (str) – user’s instance id. If None the instance id is taken from the config.json configuration file.
  • custom_url_params (dictionary of CustomUrlParameter enum and its value, i.e. {constants.CustomUrlParam.ATMFILTER:'ATMCOR'}) – dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described at http://www.sentinel-hub.com/develop/documentation/api/custom-url-parameters. Note: in case of constants.CustomUrlParam.EVALSCRIPT the dictionary value must be a string of Javascript code that is not encoded into base64.
  • time_difference (datetime.timedelta) – The time difference below which dates are deemed equal. That is, if for the given set of OGC parameters the images are available at datestimes d1<=d2<=…<=dn then only those with dk-dj>time_difference will be considered. The default time difference is negative (-1s), meaning that all dates are considered by default.
  • data_folder (str) – location of the directory where the fetched data will be saved.
class sentinelhub.data_request.FisRequest(layer, time, geometry_list, *, resolution='10m', bins=None, histogram_type=None, **kwargs)[source]

The Statistical info (or feature info service, abbreviated FIS) request class

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.

More info available at: https://www.sentinel-hub.com/develop/documentation/api/ogc_api/wcs-request

Parameters:
  • layer (str) – An ID of a layer configured in Sentinel Hub Configurator. It has to be configured for the same instance ID which will be used for this request. Also the satellite source of the layer in Configurator must match the one given by data_source parameter
  • time (str or (str, str) or datetime.date or (datetime.date, datetime.date) or datetime.datetime or (datetime.datetime, datetime.datetime)) – time or time range for which to return the results, in ISO8601 format (year-month-date, for example: 2016-01-01, or year-month-dateThours:minuts:seconds format, i.e. 2016-01-01T16:31:21). Examples: '2016-01-01', or ('2016-01-01', ' 2016-01-31')
  • geometry_list (list, [geometry.Geometry or geometry.Bbox]) – 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 coordinates should be in latitude/longitude order.
  • 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).

:type str :param bins: The number of bins (a positive integer) in the histogram. If this parameter is absent no histogram

is computed.
Type:

str

Parameters:
  • histogram_type (HistogramType) – type of histogram
  • data_source (constants.DataSource) – Source of requested satellite data. It has to be the same as defined in Sentinel Hub Configurator for the given layer. Default is Sentinel-2 L1C.
  • maxcc (float) – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.
  • instance_id (str) – user’s instance id. If None the instance id is taken from the config.json configuration file.
  • custom_url_params (dictionary of CustomUrlParameter enum and its value, i.e. {constants.CustomUrlParam.ATMFILTER:'ATMCOR'}) – dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described at http://www.sentinel-hub.com/develop/documentation/api/custom-url-parameters. Note: in case of constants.CustomUrlParam.EVALSCRIPT the dictionary value must be a string of Javascript code that is not encoded into base64.
  • data_folder (str) – location of the directory where the fetched data will be saved.
create_request()[source]

Set download requests

Create a list of DownloadRequests for all Sentinel-2 acquisitions within request’s time interval and acceptable cloud coverage.

get_dates()[source]

This method is not supported for FIS request

get_tiles()[source]

This method is not supported for FIS request

class sentinelhub.data_request.GeopediaRequest(layer, service_type, *, bbox=None, theme=None, image_format=<MimeType.PNG: 'png'>, **kwargs)[source]

The base class for Geopedia requests where all common parameters are defined.

Parameters:
  • layer (str) – Geopedia layer which contains requested data
  • service_type (constants.ServiceType) – Type of the service, supported are ServiceType.WMS and ServiceType.IMAGE
  • bbox (geometry.BBox) – Bounding box of the requested data
  • theme (str) – Geopedia’s theme endpoint string for which the layer is defined. Only required by WMS service.
  • image_format (constants.MimeType) – Format of the returned image by the Sentinel Hub’s WMS getMap service. Default is constants.MimeType.PNG.
  • data_folder (str) – Location of the directory where the fetched data will be saved.
create_request()[source]

An abstract method for logic of creating download requests

class sentinelhub.data_request.GeopediaWmsRequest(layer, theme, bbox, *, width=None, height=None, custom_url_params=None, **kwargs)[source]

Web Map Service request class for Geopedia

Creates an instance of Geopedia’s WMS (Web Map Service) GetMap request, which provides access to WMS layers in Geopedia.

Parameters:
  • layer (str) – Geopedia layer which contains requested data
  • theme (str) – Geopedia’s theme endpoint string for which the layer is defined.
  • bbox (geometry.BBox) – Bounding box of the requested data
  • width (int or None) – width (number of columns) of the returned image (array)
  • height (int or None) – height (number of rows) of the returned image (array)
  • custom_url_params (dictionary of CustomUrlParameter enum and its value, i.e. {constants.CustomUrlParam.TRANSPARENT:True}) – dictionary of CustomUrlParameters and their values supported by Geopedia’s WMS services. At the moment only the transparency is supported (CustomUrlParam.TRANSPARENT).
  • image_format (constants.MimeType) – Format of the returned image by the Sentinel Hub’s WMS getMap service. Default is constants.MimeType.PNG.
  • data_folder (str) – Location of the directory where the fetched data will be saved.
create_request()[source]

Set download requests

Create a list of DownloadRequests for all Sentinel-2 acquisitions within request’s time interval and acceptable cloud coverage.

class sentinelhub.data_request.AwsRequest(*, bands=None, metafiles=None, safe_format=False, **kwargs)[source]

The base class for Amazon Web Service request classes. Common parameters are defined here.

Collects and provides data from AWS.

AWS database is available at: http://sentinel-s2-l1c.s3-website.eu-central-1.amazonaws.com/

Parameters:
  • bands (list(str) or None) – List of Sentinel-2 bands for request. If None all bands will be obtained
  • metafiles (list(str)) – list of additional metafiles available on AWS (e.g. ['metadata', 'tileInfo', 'preview/B01', 'TCI'])
  • safe_format (bool) – flag that determines the structure of saved data. If True it will be saved in .SAFE format defined by ESA. If False it will be saved in the same structure as the stucture at AWS.
  • data_folder (str) – location of the directory where the fetched data will be saved.
create_request()[source]

An abstract method for logic of creating download requests

get_aws_service()[source]
Returns:initialized AWS service class
Return type:aws.AwsProduct or aws.AwsTile or aws_safe.SafeProduct or aws_safe.SafeTile
class sentinelhub.data_request.AwsProductRequest(product_id, *, tile_list=None, **kwargs)[source]

AWS Service request class for an ESA product

List of available products: http://sentinel-s2-l1c.s3-website.eu-central-1.amazonaws.com/#products/

Parameters:
  • product_id (str) – original ESA product identification string (e.g. 'S2A_MSIL1C_20170414T003551_N0204_R016_T54HVH_20170414T003551')
  • tile_list (list(str) or None) – list of tiles inside the product to be downloaded. If parameter is set to None all tiles inside the product will be downloaded.
  • bands (list(str) or None) – List of Sentinel-2 bands for request. If None all bands will be obtained
  • metafiles (list(str)) – list of additional metafiles available on AWS (e.g. ['metadata', 'tileInfo', 'preview/B01', 'TCI'])
  • safe_format (bool) – flag that determines the structure of saved data. If True it will be saved in .SAFE format defined by ESA. If False it will be saved in the same structure as the stucture at AWS.
  • data_folder (str) – location of the directory where the fetched data will be saved.
create_request()[source]

An abstract method for logic of creating download requests

class sentinelhub.data_request.AwsTileRequest(*, tile=None, time=None, aws_index=None, data_source=<DataSource.SENTINEL2_L1C: (<_Source.SENTINEL2: 'Sentinel-2'>, <_ProcessingLevel.L1C: 'L1C'>)>, **kwargs)[source]

AWS Service request class for an ESA tile

List of available products: http://sentinel-s2-l1c.s3-website.eu-central-1.amazonaws.com/#tiles/

Parameters:
  • tile (str) – tile name (e.g. 'T10UEV')
  • time (str) – tile sensing time in ISO8601 format
  • aws_index (int or None) – there exist Sentinel-2 tiles with the same tile and time parameter. Therefore each tile on AWS also has an index which is visible in their url path. If aws_index is set to None the class will try to find the index automatically. If there will be multiple choices it will choose the lowest index and inform the user.
  • data_source (constants.DataSource) – Source of requested AWS data. Supported sources are Sentinel-2 L1C and Sentinel-2 L2A, default is Sentinel-2 L1C data.
  • bands (list(str) or None) – List of Sentinel-2 bands for request. If None all bands will be obtained
  • metafiles (list(str)) – list of additional metafiles available on AWS (e.g. ['metadata', 'tileInfo', 'preview/B01', 'TCI'])
  • safe_format (bool) – flag that determines the structure of saved data. If True it will be saved in .SAFE format defined by ESA. If False it will be saved in the same structure as the stucture at AWS.
  • data_folder (str) – location of the directory where the fetched data will be saved.
create_request()[source]

An abstract method for logic of creating download requests

sentinelhub.data_request.get_safe_format(product_id=None, tile=None, entire_product=False, bands=None, data_source=<DataSource.SENTINEL2_L1C: (<_Source.SENTINEL2: 'Sentinel-2'>, <_ProcessingLevel.L1C: 'L1C'>)>)[source]

Returns .SAFE format structure in form of nested dictionaries. Either product_id or tile must be specified.

Parameters:
  • product_id (str) – original ESA product identification string. Default is None
  • tile ((str, str)) – tuple containing tile name and sensing time/date. Default is None
  • entire_product (bool) – in case tile is specified this flag determines if it will be place inside a .SAFE structure of the product. Default is False
  • bands (list(str) or None) – list of bands to download. If None all bands will be downloaded. Default is None
  • data_source (constants.DataSource) – In case of tile request the source of satellite data has to be specified. Default is Sentinel-2 L1C data.
Returns:

Nested dictionaries representing .SAFE structure.

Return type:

dict

sentinelhub.data_request.download_safe_format(product_id=None, tile=None, folder='.', redownload=False, entire_product=False, bands=None, data_source=<DataSource.SENTINEL2_L1C: (<_Source.SENTINEL2: 'Sentinel-2'>, <_ProcessingLevel.L1C: 'L1C'>)>)[source]

Downloads .SAFE format structure in form of nested dictionaries. Either product_id or tile must be specified.

Parameters:
  • product_id (str) – original ESA product identification string. Default is None
  • tile ((str, str)) – tuple containing tile name and sensing time/date. Default is None
  • folder (str) – location of the directory where the fetched data will be saved. Default is '.'
  • redownload (bool) – if True, download again the requested data even though it’s already saved to disk. If False, do not download if data is already available on disk. Default is False
  • entire_product (bool) – in case tile is specified this flag determines if it will be place inside a .SAFE structure of the product. Default is False
  • bands (list(str) or None) – list of bands to download. If None all bands will be downloaded. Default is None
  • data_source (constants.DataSource) – In case of tile request the source of satellite data has to be specified. Default is Sentinel-2 L1C data.
Returns:

Nested dictionaries representing .SAFE structure.

Return type:

dict