sentinelhub.api.ogc

Module for working with Sentinel Hub OGC services Sentinel Hub OGC services.

class sentinelhub.api.ogc.CustomUrlParam(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)[source]

Bases: Enum

Enum class to represent supported custom url parameters of OGC services

Supported parameters are SHOWLOGO, EVALSCRIPT, EVALSCRIPTURL, PREVIEW, QUALITY, UPSAMPLING, DOWNSAMPLING, GEOMETRY and WARNINGS.

See documentation for more information.

EVALSCRIPT = 'EvalScript'
EVALSCRIPTURL = 'EvalScriptUrl'
PREVIEW = 'Preview'
QUALITY = 'Quality'
UPSAMPLING = 'Upsampling'
DOWNSAMPLING = 'Downsampling'
GEOMETRY = 'Geometry'
MINQA = 'MinQA'
classmethod has_value(value)[source]

Tests whether CustomUrlParam contains a constant defined with a string value

Parameters:

value (str) – The string representation of the enum constant

Returns:

True if there exists a constant with a string value value, False otherwise

Return type:

bool

static get_string(param)[source]

Get custom url parameter name as string

Parameters:

param (Enum) – CustomUrlParam enum constant

Returns:

String describing the file format

Return type:

str

class sentinelhub.api.ogc.OgcRequest(layer, bbox, *, data_collection, time='latest', service_type=None, size_x=None, size_y=None, maxcc=1.0, image_format=MimeType.PNG, custom_url_params=None, time_difference=datetime.timedelta(days=-1, seconds=86399), **kwargs)[source]

Bases: DataRequest

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

Parameters:

  • layer (str) – An ID of a layer configured in Sentinel Hub Dashboard. It has to be configured for the same instance ID which will be used for this request. The satellite collection of the layer in Dashboard must also match the one given by data_collection parameter

  • bbox (BBox) – Bounding box of the requested image. Coordinates must be in the specified coordinate reference system.

  • data_collection (DataCollection) – A collection of requested satellite data. It has to be the same as defined in Sentinel Hub Dashboard for the given layer.

  • time (RawTimeType | RawTimeIntervalType) – 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:minutes: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')

  • service_type (ServiceType | None) – type of OGC service (WMS or WCS)

  • size_x (None | str | int) – number of pixels in x or resolution in x (i.e. 512 or 10m)

  • size_y (None | str | int) – number of pixels in x or resolution in y (i.e. 512 or 10m)

  • maxcc (float) – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.

  • image_format (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.

  • custom_url_params (dict[CustomUrlParam, Any] | None) – A dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described in documentation. Note: in case of 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 datetimes 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 – location of the directory where the fetched data will be saved.

  • config – A custom instance of config class to override parameters from the saved configuration.

  • kwargs (Any) –

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.

Return type:

None

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 | 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 DataCollection.DEM it returns None.

Return type:

WebFeatureService | None

class sentinelhub.api.ogc.WmsRequest(*, width=None, height=None, **kwargs)[source]

Bases: OgcRequest

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 of 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 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.

For more info check WMS documentation.

Parameters:

  • width (int | None) – width (number of columns) of the returned image (array)

  • height (int | None) – height (number of rows) of the returned image (array)

  • layer – An ID of a layer configured in Sentinel Hub Dashboard. It has to be configured for the same instance ID which will be used for this request. The satellite collection of the layer in Dashboard must also match the one given by data_collection parameter

  • bbox – Bounding box of the requested image. Coordinates must be in the specified coordinate reference system.

  • time – 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:minutes: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') (datetime.datetime, datetime.datetime)

  • data_collection – A collection of requested satellite data. It has to be the same as defined in Sentinel Hub Dashboard for the given layer. Default is Sentinel-2 L1C.

  • size_x – number of pixels in x or resolution in x (i.e. 512 or 10m)

  • size_y – number of pixels in x or resolution in y (i.e. 512 or 10m)

  • maxcc – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.

  • image_format – 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.

  • custom_url_params – A dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described in documentation. Note: in case of CustomUrlParam.EVALSCRIPT the dictionary value must be a string of Javascript code that is not encoded into base64.

  • time_difference – The time difference below which dates are deemed equal. That is, if for the given set of OGC parameters the images are available at datetimes 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 – location of the directory where the fetched data will be saved.

  • config – A custom instance of config class to override parameters from the saved configuration.

  • kwargs (Any) –

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

Bases: OgcRequest

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 of WCS request the user specifies the desired resolution of the image instead of its size.

For more info check WCS documentation.

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.

  • layer – An ID of a layer configured in Sentinel Hub Dashboard. It has to be configured for the same instance ID which will be used for this request. The satellite collection of the layer in Dashboard must also match the one given by data_collection parameter

  • bbox – Bounding box of the requested image. Coordinates must be in the specified coordinate reference system.

  • time – 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:minutes: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') (datetime.datetime, datetime.datetime)

  • data_collection – A collection of requested satellite data. It has to be the same as defined in Sentinel Hub Dashboard for the given layer. Default is Sentinel-2 L1C.

  • size_x – number of pixels in x or resolution in x (i.e. 512 or 10m)

  • size_y – number of pixels in x or resolution in y (i.e. 512 or 10m)

  • maxcc – maximum accepted cloud coverage of an image. Float between 0.0 and 1.0. Default is 1.0.

  • image_format – 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.

  • custom_url_params – A dictionary of CustomUrlParameters and their values supported by Sentinel Hub’s WMS and WCS services. All available parameters are described in documentation. Note: in case of CustomUrlParam.EVALSCRIPT the dictionary value must be a string of Javascript code that is not encoded into base64.

  • time_difference – The time difference below which dates are deemed equal. That is, if for the given set of OGC parameters the images are available at datetimes 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 – location of the directory where the fetched data will be saved.

  • config – A custom instance of config class to override parameters from the saved configuration.

  • kwargs (Any) –

class sentinelhub.api.ogc.OgcImageService(config=None)[source]

Bases: object

Sentinel Hub OGC services class for providing image data

Intermediate layer between QGC-type requests (WmsRequest and WcsRequest) and the Sentinel Hub OGC (WMS and WCS) services.

Parameters:

config (SHConfig | None) – A custom instance of config class to override parameters from the saved configuration.

get_request(request)[source]

Get download requests

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

Parameters:

request (OgcRequest) – QGC-type request with specified bounding box, time interval, and cloud coverage for specific product.

Returns:

list of DownloadRequests

Return type:

list[sentinelhub.download.models.DownloadRequest]

get_url(request, *, date=None, size_x=None, size_y=None, geometry=None)[source]

Returns url to Sentinel Hub’s OGC service for the product specified by the OgcRequest and date.

Parameters:

  • request (OgcRequest) – OGC-type request with specified bounding box, cloud coverage for specific product.

  • date (datetime | None) – acquisition date or None

  • size_x (None | str | int) – horizontal image dimension

  • size_y (None | str | int) – vertical image dimension

  • geometry (None | BBox | Geometry) –

Returns:

url to Sentinel Hub’s OGC service for this product.

Return type:

str

get_base_url(request)[source]

Creates base url string.

Parameters:

request (OgcRequest) – OGC-type request with specified bounding box, cloud coverage for specific product.

Returns:

base string for url to Sentinel Hub’s OGC service for this product.

Return type:

str

get_dates(request)[source]

Get available Sentinel-2 acquisitions at least time_difference apart

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.

When a time_difference threshold is set to a positive value, the function filters out all datetimes which are within the time difference. The oldest datetime is preserved, all others all deleted.

Parameters:

request (OgcRequest) – OGC-type request

Returns:

List of dates of existing acquisitions for the given request

Return type:

list[datetime.datetime | None]

static get_image_dimensions(request)[source]

Verifies or calculates image dimensions.

Parameters:

request (OgcRequest) – OGC-type request

Returns:

horizontal and vertical dimensions of requested image

Return type:

tuple[int | str, int | str]

get_wfs_iterator()[source]

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

Returns:

Iterator of dictionaries containing info about all satellite tiles used in the request. In case of DataCollection.DEM it returns None.

Return type:

WebFeatureService | None