sentinelhub.api.catalog

A client interface for Sentinel Hub Catalog API.

class sentinelhub.api.catalog.SentinelHubCatalog(config=None)[source]

Bases: SentinelHubService

The main class for interacting with Sentinel Hub Catalog API

For more details about certain endpoints and parameters check Catalog API documentation.

Parameters:

config (SHConfig | None) – A configuration object with required parameters sh_client_id, sh_client_secret, and sh_auth_base_url which is used for authentication and sh_base_url which defines the service deployment that will be used.

get_info()[source]

Provides the main information that define Sentinel Hub Catalog API

Catalog API reference

Returns:

A service payload with information

Return type:

Dict[str, Any]

get_conformance()[source]

Get information about specifications that this API conforms to

Catalog API reference

Returns:

A service payload with information

Return type:

Dict[str, Any]

get_collections()[source]

Provides a list of collections that are available to a user

Catalog API reference

Returns:

A list of collections with information

Return type:

List[Dict[str, Any]]

get_collection(collection)[source]

Provides information about given collection

Catalog API reference

Parameters:

collection (DataCollection | str) – A data collection object or a collection ID

Returns:

Information about a collection

Return type:

Dict[str, Any]

get_feature(collection, feature_id)[source]

Provides information about a single feature in a collection

Catalog API reference

Parameters:

  • collection (DataCollection) – A data collection object or a collection ID

  • feature_id (str) – A feature ID

Returns:

Information about a feature in a collection

Return type:

Dict[str, Any]

search(collection, *, time=None, bbox=None, geometry=None, ids=None, filter=None, filter_lang='cql2-text', filter_crs=None, fields=None, distinct=None, limit=100, **kwargs)[source]

Catalog STAC search

Catalog API reference

Parameters:

  • collection (DataCollection | str) – A data collection object or a collection ID

  • time (None | str | date | Tuple[None | str | date, None | str | date]) – A time interval or a single time. It can either be a string in form YYYY-MM-DDThh:mm:ss or YYYY-MM-DD or a datetime object

  • bbox (BBox | None) – A search bounding box, it will always be reprojected to WGS 84 before being sent to the service. Re-projection will be done with BBox.transform_bounds method which can produce a slightly larger bounding box. If that is a problem then transform a BBox object into a Geometry object and search with geometry parameter instead.

  • geometry (Geometry | None) – A search geometry, it will always reprojected to WGS 84 before being sent to the service. This parameter is defined with parameter intersects at the service.

  • ids (List[str] | None) – A list of feature ids as defined in service documentation

  • filter (None | str | Dict[str, Any]) – A STAC filter in CQL2, described in Catalog API documentation

  • filter_lang (Literal['cql2-text', 'cql2-json']) – How to parse CQL2 of the filter input, described in Catalog API documentation

  • filter_crs (str | None) – The CRS used by spatial literals in the ‘filter’ value, provided in URI form. Example input is “http://www.opengis.net/def/crs/OGC/1.3/CRS84”

  • fields (Dict[str, Any] | None) – A dictionary of fields to include or exclude described in Catalog API documentation

  • distinct (str | None) – A special query attribute described in Catalog API documentation

  • limit (int) – A number of results to return per each request. At the end iterator will always provide all results the difference is only in how many requests it will have to make in the background.

  • kwargs (Any) – Any other parameters that will be passed directly to the service

Return type:

CatalogSearchIterator

class sentinelhub.api.catalog.CatalogSearchIterator(*args, **kwargs)[source]

Bases: FeatureIterator[Dict[str, Any]]

Searches a catalog with a given query and provides results

Parameters:

  • client – An instance of a download client object

  • url – A URL where requests will be made

  • params – Parameters to be sent with each request

get_timestamps()[source]

Provides features timestamps

Returns:

A list of sensing times

Return type:

List[datetime]

get_geometries()[source]

Provides features geometries

Returns:

A list of geometry objects with CRS

Return type:

List[Geometry]

get_ids()[source]

Provides features IDs

Returns:

A list of IDs

Return type:

List[str]

sentinelhub.api.catalog.get_available_timestamps(bbox, time_interval, data_collection, *, time_difference=None, ignore_tz=True, maxcc=None, config=None)[source]

Helper function to search for all available timestamps for a given area and query parameters.

Parameters:

  • bbox (BBox) – A bounding box of the search area.

  • data_collection (DataCollection) – A collection specifying the satellite data source for finding available timestamps.

  • time_interval (Tuple[None | str | date, None | str | date] | None) – A time interval from which to provide the timestamps.

  • time_difference (timedelta | None) – Shortest allowed time difference. Consecutive timestamps will be skipped if too close to the previous one. Defaults to keeping all timestamps.

  • ignore_tz (bool) – Ignore the time zone part in the returned timestamps. Default is True.

  • maxcc (float | None) – Maximum cloud coverage filter from interval [0, 1]. Default is None.

  • config (SHConfig | None) – The SH configuration object.

Returns:

A list of timestamps of available observations.

Return type:

List[datetime]