API

Catalogue, collections and products

class terracatalogueclient.client.Catalogue(config=None)[source]

Connection to a catalogue endpoint, which allows for searching and downloading EO products.

Parameters:

config (CatalogueConfig) – catalogue configuration. If none is supplied, the default Terrascope config is used.

authenticate()[source]

Authenticate to the catalogue in an interactive way. A browser window will open to handle the sign-in procedure.

Return type:

Catalogue

Returns:

the catalogue object

authenticate_non_interactive(username, password)[source]

Authenticate to the catalogue in a non-interactive way. This requires you to pass your user credentials directly in the code.

Parameters:

  • username (str) – username

  • password (str) – password

Return type:

Catalogue

Returns:

the catalogue object

download_file(product_file, path)[source]

Download a single product file.

Parameters:

  • product_file (ProductFile) – product file to download

  • path (str) – output directory to write the file to

download_product(product, path, file_types=ProductFileType.ALL, raise_on_failure=True)[source]

Download a single product. This will download all files belonging to the given product.

Parameters:

  • product (Product) – product to download

  • path (str) – output directory to write files to

  • file_types (ProductFileType) – type of product files to download

  • raise_on_failure (bool) – raise an exception on a failure or silently continue

download_products(products, path, file_types=ProductFileType.ALL, force=False, raise_on_failure=True)[source]

Download the given products. This will download the files belonging to the given products matching the provided file types.

Parameters:

  • products (Iterable[Product]) – iterable of products to download

  • path (str) – output directory to write files to

  • file_types (ProductFileType) – type of product files to download

  • force (bool) – skip download confirmation

  • raise_on_failure (bool) – raise an exception on a failure or silently continue

get_collections(start=None, end=None, bbox=None, geometry=None, platform=None, **kwargs)[source]

Get the collections in the catalogue.

Parameters:

  • start (Union[str, date, datetime, None]) – start of the temporal interval to search

  • end (Union[str, date, datetime, None]) – end of the temporal interval to search

  • bbox (Union[str, List[Union[int, float]], Dict[str, Union[int, float]], None]) – geographic bounding box as list or dict (west, south, east, north)

  • geometry (Union[str, BaseGeometry, None]) – geometry as WKT string or Shapely geometry

  • platform (Optional[str]) – acquisition platform

  • **kwargs – additional query parameters can be provided as keyword arguments

Return type:

Iterator[Collection]

get_product_count(collection, **kwargs)[source]

Get the count of products matching the query.

This is significantly more efficient than loading all results and then counting.

Parameters:

  • collection (str) – collection to query

  • **kwargs – query parameters, check get_products() for more information on query parameters

get_products(collection, start=None, end=None, bbox=None, geometry=None, title=None, productType=None, relativeOrbitNumber=None, orbitDirection=None, cloudCover=None, tileId=None, productGroupId=None, publicationDate=None, modificationDate=None, accessedFrom=None, limit=None, **kwargs)[source]

Get the products matching the query.

Parameters:

  • collection (str) – collection to query

  • start (Union[str, date, datetime, None]) – start of the temporal interval to search

  • end (Union[str, date, datetime, None]) – end of the temporal interval to search

  • bbox (Union[str, List[Union[int, float]], Dict[str, Union[int, float]], None]) – geographic bounding box as list or dict (west, south, east, north)

  • geometry (Union[str, BaseGeometry, None]) – geometry as WKT string or Shapely geometry

  • title (Optional[str]) – title of the product

  • productType (Optional[str]) – product type

  • relativeOrbitNumber (Union[int, str, None]) – relative acquisition orbit number

  • orbitDirection (Optional[str]) – acquisition orbit direction

  • cloudCover (Union[Tuple[Union[float, int, None], Union[float, int, None]], float, int, str, None]) – maximum cloud cover percentage as int/float; cloud cover percentage interval as tuple; or number, set or interval of cloud cover percentages as a str

  • tileId (Optional[str]) – tile identifier

  • productGroupId (Optional[str]) – string identifying the particular group to which a product belongs

  • publicationDate (Union[Tuple[Union[date, datetime, str, None], Union[date, datetime, str, None]], str, None]) – date of publication, as a date range in a date/datetime tuple (you can use None to have an unbounded interval) or as a str

  • modificationDate (Union[Tuple[Union[date, datetime, str, None], Union[date, datetime, str, None]], str, None]) – date of publication, as a date range in a date/datetime tuple (you can use None to have an unbounded interval) or as a str

  • accessedFrom (Optional[str]) – information on the origin of the request

  • limit (Optional[int]) – limit the number of requested products

  • **kwargs – additional query parameters can be provided as keyword arguments

Return type:

Iterator[Product]

class terracatalogueclient.client.Collection(id, geojson, geometry, bbox, properties)[source]

Collection returned from a catalogue search.

Variables:

  • id (str) – collection identifier

  • geojson (dict) – GeoJSON representation of the collection

  • geometry (BaseGeometry) – collection geometry as a Shapely geometry

  • bbox (List[float]) – bounding box

  • properties (dict) – collection properties

class terracatalogueclient.client.Product(id, title, geojson, geometry, bbox, beginningDateTime, endingDateTime, properties, data, related, previews, alternates)[source]

Product entry returned from a catalogue search.

Variables:

  • id (str) – product identifier

  • title (str) – product title

  • geojson (dict) – GeoJSON representation of the product

  • geometry (BaseGeometry) – product geometry as a Shapely geometry

  • bbox (List[float]) – bounding box

  • beginningDateTime (dt.datetime) – acquisition start date time

  • endingDateTime (dt.datetime) – acquisition end date time

  • properties (dict) – product properties

  • data (List[ProductFile]) – product data files

  • related (List[ProductFile]) – related resources (eg. cloud mask)

  • previews (List[ProductFile]) – previews or quicklooks of the product

  • alternates (List[ProductFile]) – metadata description in an alternative format

class terracatalogueclient.client.ProductFile(href, length, title=None, type=None, category=None)[source]

File that belongs to a product.

Variables:

  • href (str) – URI locator of the product file

  • length (Optional[int]) – content length in bytes

  • title (Optional[str]) – title of the product file

  • type (Optional[str]) – content type

  • category (Optional[str]) – category, only applicable for previews or related files

flag terracatalogueclient.client.ProductFileType(value)[source]

Enum flag to indicate the type of a product file.

Valid values are as follows:

DATA = <ProductFileType.DATA: 1>
RELATED = <ProductFileType.RELATED: 2>
PREVIEWS = <ProductFileType.PREVIEWS: 4>
ALTERNATES = <ProductFileType.ALTERNATES: 8>

Configuration

class terracatalogueclient.config.CatalogueConfig(config)[source]

Catalogue configuration object.

Parameters:

config (ConfigParser) – configuration

static from_environment(environment, path=None)[source]

Get a catalogue configuration object from a pre-defined environment.

Parameters:

  • environment (CatalogueEnvironment) – the pre-defined environment

  • path (str) – optional path of the catalogue .ini configuration file containing values to override the pre-defined environment config

Return type:

CatalogueConfig

Returns:

CatalogueConfig object

static from_file(path)[source]

Get a catalogue configuration object from a configuration file.

Parameters:

path (str) – path of the catalogue .ini configuration file

Return type:

CatalogueConfig

Returns:

CatalogueConfig object

enum terracatalogueclient.config.CatalogueEnvironment(value)[source]

Catalogue environment object.

Valid values are as follows:

TERRASCOPE = <CatalogueEnvironment.TERRASCOPE: 'terrascope.ini'>
HRVPP = <CatalogueEnvironment.HRVPP: 'hrvpp.ini'>
CGLS = <CatalogueEnvironment.CGLS: 'cgls.ini'>

Exceptions

exception terracatalogueclient.exceptions.ParameterParserException[source]

Raised when a parameter value cannot be parsed.

exception terracatalogueclient.exceptions.ProductDownloadException[source]

Raised when the product cannot be downloaded.

exception terracatalogueclient.exceptions.SearchException(response, *args)[source]

Raised when the search operation cannot be executed.

Follows the OpenSearch GeoJSON Response Encoding specification: https://docs.opengeospatial.org/is/17-047r1/17-047r1.html#39

Variables:

  • response (requests.Response) – error response

  • body (dict) – JSON body of the response

  • search_exceptions (list) – list of reported search exceptions

exception terracatalogueclient.exceptions.TooManyResultsException[source]

Raised when the query returns too many results.