TerraCatalogue Client

https://vitobelgium.github.io/terracatalogueclient/
Admin
TerraCatalogueClient is a Python client for the Terrascope and HRVPP EO catalogues, using the...
Tokens:16,919
Snippets:139
Trust Score:9.7
Update:4 months ago
Show doc for...
Tokens:
Raw
### Configuration File Structure Example

Source: https://vitobelgium.github.io/terracatalogueclient/usage.html

An example INI file structure for catalogue configuration, including sections for Catalogue, Auth, HTTP, and S3.

```ini
[Catalogue]
URL = https://services.terrascope.be/catalogue/

[Auth]
ClientId = terracatalogueclient
ClientSecret =
TokenEndpoint = https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/token
AuthorizationEndpoint = https://sso.terrascope.be/auth/realms/terrascope/protocol/openid-connect/auth
InteractiveSupported = True
NonInteractiveSupported = True

[HTTP]
ChunkSize = 2097152

# S3 is not supported by the Terrascope catalogue, so configuration is empty
[S3]
AccessKey =
SecretKey =
EndpointUrl =
```

--------------------------------

### Install from PyPI

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/installation.rst.txt

Use this command to install the package directly from the Python Package Index.

```bash
pip install terracatalogueclient
```

--------------------------------

### Install from Terrascope Repository

Source: https://vitobelgium.github.io/terracatalogueclient/installation.html

Install the package from the public Terrascope repository using an extra index URL.

```bash
pip install –extra-index-url https://artifactory.vgt.vito.be/artifactory/api/pypi/python-packages-public/simple terracatalogueclient
```

--------------------------------

### Install from Terrascope Repository

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/installation.rst.txt

Use this command to install the package from the Terrascope public repository, which hosts additional or specific versions.

```bash
pip install --extra-index-url https://artifactory.vgt.vito.be/artifactory/api/pypi/python-packages-public/simple terracatalogueclient
```

--------------------------------

### Get CatalogueConfig from File

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/config.html

Creates a CatalogueConfig object from a specified INI file path. This allows overriding default environment configurations with custom settings.

```python
    @staticmethod
    def from_file(path: str) -> "CatalogueConfig":
        """
        Get a catalogue configuration object from a configuration file.

        :param path: path of the catalogue .ini configuration file
        :return: CatalogueConfig object
        """
        return CatalogueConfig.from_environment(CatalogueEnvironment.TERRASCOPE, path)





```

--------------------------------

### Get Product Directory Path

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Constructs a product directory path by joining a base path with the product ID. Handles potential errors in ID formatting.

```python
    @staticmethod
    def _get_product_dir(path: str, product: Product):
        try:
            return os.path.join(path, product.id[product.id.rindex(":") + 1 :])
        except ValueError:
            return os.path.join(path, product.id)
```

--------------------------------

### Get Products with Query Parameters

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Retrieves products from the catalogue based on specified criteria. Supports temporal, spatial, and metadata filtering. Use this to fetch product data.

```python
def get_products(
        self,
        collection: str,
        start: Optional[Union[str, dt.date, dt.datetime]] = None,
        end: Optional[Union[str, dt.date, dt.datetime]] = None,
        bbox: Optional[
            Union[str, List[Union[int, float]], Dict[str, Union[int, float]]]
        ] = None,
        geometry: Optional[Union[str, BaseGeometry]] = None,
        title: Optional[str] = None,
        productType: Optional[str] = None,
        relativeOrbitNumber: Optional[Union[int, str]] = None,
        orbitDirection: Optional[str] = None,
        cloudCover:
            Optional[
                Union[
                    Tuple[Union[float, int, None], Union[float, int, None]], float, int, str
                ]
            ] = None,
        tileId: Optional[str] = None,
        productGroupId: Optional[str] = None,
        publicationDate:
            Optional[
                Union[
                    Tuple[
                        Union[dt.date, dt.datetime, str, None],
                        Union[dt.date, dt.datetime, str, None],
                    ],
                    str,
                ]
            ] = None,
        modificationDate:
            Optional[
                Union[
                    Tuple[
                        Union[dt.date, dt.datetime, str, None],
                        Union[dt.date, dt.datetime, str, None],
                    ],
                    str,
                ]
            ] = None,
        accessedFrom: Optional[str] = None,
        limit: Optional[int] = None,
        **kwargs,
    ) -> Iterator[Product]:
        """Get the products matching the query.

        :param collection: collection to query
        :param start: start of the temporal interval to search
        :param end: end of the temporal interval to search
        :param bbox: geographic bounding box as list or dict (west, south, east, north)
        :param geometry: geometry as WKT string or Shapely geometry
        :param title: title of the product
        :param productType: product type
        :param relativeOrbitNumber: relative acquisition orbit number
        :param orbitDirection: acquisition orbit direction
        :param cloudCover: 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
        :param tileId: tile identifier
        :param productGroupId: string identifying the particular group to which a product belongs
        :param publicationDate: 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
        :param modificationDate: 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
        :param accessedFrom: information on the origin of the request
        :param limit: limit the number of requested products
        :param **kwargs: additional query parameters can be provided as keyword arguments
        """
        url = urljoin(self.config.catalogue_url, "products")
        kwargs["collection"] = collection
        if start:
            kwargs["start"] = start
        if end:
            kwargs["end"] = end
        if bbox:
            kwargs["bbox"] = bbox
        if geometry:
            kwargs["geometry"] = geometry
        if title:
            kwargs["title"] = title
        if productType:
            kwargs["productType"] = productType
        if relativeOrbitNumber:
            kwargs["relativeOrbitNumber"] = relativeOrbitNumber
        if orbitDirection:
            kwargs["orbitDirection"] = orbitDirection
        if cloudCover:
            kwargs["cloudCover"] = cloudCover
        if tileId:
            kwargs["tileId"] = tileId
        if productGroupId:
            kwargs["productGroupId"] = productGroupId
        if publicationDate:
            kwargs["publicationDate"] = publicationDate
        if modificationDate:
            kwargs["modificationDate"] = modificationDate
        if accessedFrom:
            kwargs["accessedFrom"] = accessedFrom
        if limit:
            kwargs["limit"] = limit
        self._convert_parameters(kwargs)
        return self._get_paginated_feature_generator(url, kwargs, self._build_product)

```

--------------------------------

### Get CatalogueConfig from Environment

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/config.html

Creates a CatalogueConfig object from a predefined environment, optionally overriding settings with a custom INI file. This is useful for setting up configurations for different catalogue environments.

```python
    @staticmethod
    def from_environment(
        environment: CatalogueEnvironment,
        path: str = None
    ) -> "CatalogueConfig":
        """
        Get a catalogue configuration object from a pre-defined environment.

        :param environment: the pre-defined environment
        :param path: optional path of the catalogue .ini configuration file containing values to override the
            pre-defined environment config
        :return: CatalogueConfig object
        """
        config = configparser.ConfigParser()
        # read the default config first to populate default values
        config.read_string(
            pkgutil.get_data(__name__, "resources/" + environment.value).decode()
        )
        if path is not None:
            # apply values from custom config
            config.read(path)

        return CatalogueConfig(config)




```

--------------------------------

### Get Product Count

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Efficiently retrieves the number of products matching a query without fetching all product data. Use this when only the count is needed.

```python
def get_product_count(self, collection: str, **kwargs):
        """Get the count of products matching the query.

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

        :param collection: collection to query
        :param **kwargs: query parameters, check :meth:`~terracatalogueclient.client.Catalogue.get_products` for more information on query parameters
        """
        url = urljoin(self.config.catalogue_url, "products")
        kwargs["collection"] = collection
        kwargs["count"] = 0
        self._convert_parameters(kwargs)
        response = self._session_search.get(url, params=kwargs, timeout=_SEARCH_TIMEOUT)
        logger.debug(f"{response.request.url} - {response.status_code}")
        if response.status_code == requests.codes.ok:
            response_json = response.json()

```

--------------------------------

### Get Local Product Paths (MEP)

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Retrieves product information, specifically obtaining local paths for products when running in the Terrascope Notebooks or VM environment. Use the 'accessedFrom="MEP"' parameter.

```python
products = catalogue.get_products(
    collection="urn:eop:VITO:TERRASCOPE_S2_FAPAR_V2",
    start="2021-02-01",
    end="2021-02-28",
    tileId="31UGS",
    resolution=20,
    accessedFrom="MEP"  # get local path
)

# href of the product file now contains the local path
local_paths = [pf.href for p in products for pf in p.data]
```

--------------------------------

### Get Product Count Per Collection

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Efficiently retrieves the number of products for each collection within a specified date range. This is more performant than fetching all products and then counting them.

```python
collections = catalogue.get_collections()
for collection in collections:
    count = catalogue.get_product_count(
        collection.id,
        start=dt.date(2019, 1, 1),
        end=dt.date(2020, 1, 1)
    )
    print(f"{collection.id}: {count}")
```

--------------------------------

### Get Product Counts Per Collection

Source: https://vitobelgium.github.io/terracatalogueclient/usage.html

Efficiently retrieves the number of products for each collection within a specified date range using `get_product_count()`.

```python
collections = catalogue.get_collections()
for collection in collections:
    count = catalogue.get_product_count(
        collection.id,
        start=dt.date(2019, 1, 1),
        end=dt.date(2020, 1, 1)
    )
    print(f"{collection.id}: {count}")

```

--------------------------------

### Initialize Catalogue with Custom Configuration

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Use this snippet to create a Catalogue object with a custom configuration file. Ensure the configuration file path is correct.

```python
from terracatalogueclient import Catalogue
from terracatalogueclient.config import CatalogueConfig

config = CatalogueConfig.from_file("/path/to/configuration.ini")
catalogue = Catalogue(config)  # catalogue with custom configuration
```

--------------------------------

### Initialize Catalogue with Pre-defined HR-VPP Configuration

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Use this snippet to initialize the Catalogue client for the HR-VPP catalogue using a pre-defined environment configuration.

```python
from terracatalogueclient import Catalogue
from terracatalogueclient.config import CatalogueConfig, CatalogueEnvironment

config = CatalogueConfig.from_environment(CatalogueEnvironment.HRVPP)
catalogue = Catalogue(config)
```

--------------------------------

### Build Product File from Link

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Constructs a ProductFile object from a dictionary representing a link. Extracts href, length, title, type, and category.

```python
    @staticmethod
    def _build_file(link: dict) -> ProductFile:
        href = link.get("href")
        length = link.get("length", None)
        title = link.get("title", None)
        type = link.get("type", None)
        category = link.get("category", None)
        return ProductFile(href, length, title, type, category)
```

--------------------------------

### Initialize S3 Client

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Sets up the S3 resource service client using configuration values. Requires S3 endpoint URL, access key, and secret key to be provided.

```python
def _init_s3_client(self):
        """Set up the S3 resource service client using the configuration values."""
        # disable bucket name validation: https://creodias.eu/-/bucket-sharing-using-s3-bucket-policy
        logger.info("Initializing S3 client")
        botocore_session = botocore.session.Session()
        botocore_session.unregister(
            "before-parameter-build.s3", botocore.handlers.validate_bucket_name
        )
        boto3.setup_default_session(botocore_session=botocore_session)

        if not (
            self.config.s3_endpoint_url
            and self.config.s3_access_key
            and self.config.s3_secret_key
        ):
            raise ProductDownloadException(
                "Please provide S3 endpoint and credentials in the configuration file "
                "or using environment variables in order to use S3 as a download method."
            )

        self.s3 = boto3.resource(
            "s3",
            endpoint_url=self.config.s3_endpoint_url,
            aws_access_key_id=self.config.s3_access_key,
            aws_secret_access_key=self.config.s3_secret_key,
        )
```

--------------------------------

### Initialize Catalogue with Default Terrascope Configuration

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

This snippet shows how to initialize the Catalogue client using the default Terrascope configuration when no specific configuration is provided.

```python
from terracatalogueclient import Catalogue
catalogue = Catalogue()  # catalogue with default Terrascope configuration
```

--------------------------------

### Get Catalogue Collections

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Retrieves collections from the catalogue, optionally filtering by date range, bounding box, geometry, or platform. Supports additional query parameters.

```python
catalogue.get_collections(start="2023-01-01", end="2023-12-31", bbox=[-10, -20, 30, 40], platform="sentinel-1")
```

--------------------------------

### Download Multiple Products

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Initiates the download of multiple products. It prompts for confirmation based on the total size and then calls download_product for each.

```python
def download_products(
        self,
        products: Iterable[Product],
        path: str,
        file_types: ProductFileType = ProductFileType.ALL,
        force: bool = False,
        raise_on_failure: bool = True,
    ):
        """
        Download the given products. This will download the files belonging to the given products matching the provided file types.

        :param products: iterable of products to download
        :param path: output directory to write files to
        :param file_types: type of product files to download
        :param force: skip download confirmation
        :param raise_on_failure: raise an exception on a failure or silently continue
        """
        products = list(products)
        if not force:
            confirmed = False
            while not confirmed:
                in_confirmation = input(
                    f"You are about to download {humanfriendly.format_size(self._get_total_file_size(products, file_types))}, do you want to continue? [Y/n] "
                )
                if any(in_confirmation.lower() == s for s in ["y", ""]):
                    confirmed = True
                elif in_confirmation.lower() == "n":
                    return
        for product in products:
            self.download_product(product, path, file_types, raise_on_failure)
```

--------------------------------

### Download Products via S3 Access Method

Source: https://vitobelgium.github.io/terracatalogueclient/usage.html

Queries products for S3 access and then downloads them. Requires S3 endpoint and credentials to be configured.

```python
products = catalogue.get_products(
    collection=collection,
    start="2021-01-01",
    end="2021-02-01",
    tileId="31UES",
    accessedFrom="S3"
)
# download automatically selects the access method specified when querying the products
catalogue.download_products(products, path)


```

--------------------------------

### Download Product File via S3

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Downloads a single product file using an S3 session. Assumes the product file's href contains a valid S3 link. Initializes the S3 client if not already done.

```python
def _download_file_s3(self, product_file: ProductFile, path: str):
        """Download a single product over S3.
        Assumes that the href in the product file contains a valid S3 link.

        :param product_file: product file to download
        :param path: output directory to write the file to
        """
        if not os.path.exists(path):
            logger.debug(f"Creating output directory {path}")
            os.makedirs(path)
        filename = os.path.basename(product_file.href)
        out_path = os.path.join(path, filename)

        if not self.s3:
            self._init_s3_client()

        logger.info(f"Downloading {product_file.href} to {out_path}")
        _, tmp = product_file.href.split("://", 1)
        bucket_name, key = tmp.split("/", 1)
        bucket = self.s3.Bucket(bucket_name)
        bucket.download_file(key, out_path)
```

--------------------------------

### Download Product File via HTTP

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Downloads a single product file using an HTTP session. Creates the output directory if it does not exist. Handles file streaming and writing in chunks.

```python
def _download_file_http(self, product_file: ProductFile, path: str):
        """Download a single product over HTTP.

        :param product_file: product file to download
        :param path: output directory to write the file to
        """
        # Check if the user is authorized to download the product
        if not self._is_authorized_to_download_http(product_file):
            raise ProductDownloadException(
                "You are not authorized to download this product. Make sure you are authenticated to the catalogue."
            )
        # create output directory if it doesn't exist
        if not os.path.exists(path):
            logger.debug(f"Creating output directory {path}")
            os.makedirs(path)
        filename = os.path.basename(product_file.href)
        out_path = os.path.join(path, filename)
        logger.info(f"Downloading {product_file.href} to {out_path}")
        with self._session_download.get(
            product_file.href,
            stream=True,
            allow_redirects=False,
            timeout=_DOWNLOAD_TIMEOUT,
        ) as r:
            r.raise_for_status()
            with open(out_path, "wb") as f:
                for chunk in r.iter_content(
                    chunk_size=self.config.http_download_chunk_size
                ):
                    if chunk:
                        f.write(chunk)
```

--------------------------------

### Get paginated feature generator

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Retrieves features from a paginated API endpoint, yielding them one by one. It handles multiple pages and applies an optional limit. Raises TooManyResultsException if the total results exceed a reasonable threshold.

```python
def _get_paginated_feature_generator(self, url: str, url_params: dict, builder) -> Iterator:
    limit = url_params.pop("limit", None)
    feature_count = 0

    response = self._session_search.get(
        url, params=url_params, timeout=_SEARCH_TIMEOUT
    )
    logger.debug(f"{response.request.url} - {response.status_code}")

    if response.status_code == requests.codes.ok:
        response_json = response.json()
        if not Catalogue._can_get_all_features(response_json, limit):
            raise TooManyResultsException(
                f"Too many results: {response_json['totalResults']} found. "
                f"Please narrow down your search."
            )

        for f in response_json["features"]:
            feature_count += 1
            yield builder(f)
            if limit is not None and feature_count >= limit:
                return

        while "next" in response_json["properties"]["links"]:
            url = response_json["properties"]["links"]["next"][0]["href"]
            response = self._session_search.get(url, timeout=_SEARCH_TIMEOUT)
            logger.debug(f"{response.request.url} - {response.status_code}")

            if response.status_code == requests.codes.ok:
                response_json = response.json()
                for f in response_json["features"]:
                    feature_count += 1
                    yield builder(f)
                    if limit is not None and feature_count >= limit:
                        return
            else:
                response.raise_for_status()
    else:
        raise SearchException(response)
```

--------------------------------

### Download Single Product File

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Handles the download of a single product file based on its protocol. It delegates to specific download methods for HTTP and S3 protocols.

```python
def download_file(self, product_file: ProductFile, path: str):
        """Download a single product file.

        :param product_file: product file to download
        :param path: output directory to write the file to
        """
        protocol = product_file.get_protocol()
        if protocol.startswith("http"):
            self._download_file_http(product_file, path)
        elif protocol == "s3":
            self._download_file_s3(product_file, path)
        else:
            raise ProductDownloadException(
                f"Could not download product file, {product_file.href} is not a downloadable path."
            )
```

--------------------------------

### download_file

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Downloads a single product file to a specified directory.

```APIDOC
## download_file(product_file, path)

Downloads a single product file to the specified output directory.

### Parameters
* **product_file** (`ProductFile`) - The product file object to download.
* **path** (`str`) - The output directory where the file will be saved.
```

--------------------------------

### Custom Exception: ProductDownloadException

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/exceptions.html

Raised when a product cannot be downloaded. This exception is a simple custom exception class.

```python
class ProductDownloadException(Exception):
    """Raised when the product cannot be downloaded."""

    pass
```

--------------------------------

### CatalogueConfig Class Initialization

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/config.html

Initializes the CatalogueConfig object by parsing a ConfigParser object and extracting configuration values for Catalogue, Auth, HTTP, and S3 sections. It also handles overriding S3 credentials with environment variables.

```python
class CatalogueConfig:
    """Catalogue configuration object."""

    def __init__(self, config: configparser.ConfigParser):
        """
        :param config: configuration
        """
        self.config = config

        # Catalogue
        self.catalogue_url = config.get("Catalogue", "URL").rstrip("/") + "/"

        # Auth
        self.oidc_client_id = config.get("Auth", "ClientId")
        self.oidc_client_secret = config.get("Auth", "ClientSecret")
        self.oidc_token_endpoint = config.get("Auth", "TokenEndpoint")
        self.oidc_authorization_endpoint = config.get("Auth", "AuthorizationEndpoint")
        self.oidc_interactive_supported = config.getboolean(
            "Auth", "InteractiveSupported"
        )
        self.oidc_non_interactive_supported = config.getboolean(
            "Auth", "NonInteractiveSupported"
        )

        # HTTP
        self.http_download_chunk_size = config.getint("HTTP", "ChunkSize")

        # S3
        self.s3_endpoint_url = config.get("S3", "EndpointUrl")
        # allow override of S3 credentials using environment variables
        if "AWS_ACCESS_KEY_ID" in os.environ and os.environ["AWS_ACCESS_KEY_ID"]:
            self.s3_access_key = os.environ["AWS_ACCESS_KEY_ID"]
        else:
            self.s3_access_key = config.get("S3", "AccessKey")

        if (
            "AWS_SECRET_ACCESS_KEY" in os.environ
            and os.environ["AWS_SECRET_ACCESS_KEY"]
        ):
            self.s3_secret_key = os.environ["AWS_SECRET_ACCESS_KEY"]
        else:
            self.s3_secret_key = config.get("S3", "SecretKey")

    @staticmethod
    def get_default_config() -> "CatalogueConfig":
        return CatalogueConfig.from_environment(CatalogueEnvironment.TERRASCOPE)





```

--------------------------------

### download_product

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Downloads all files associated with a single product to a specified directory.

```APIDOC
## download_product(product, path, file_types=ProductFileType.ALL, raise_on_failure=True)

Downloads a single product, including all its associated files. Allows specifying file types and error handling behavior.

### Parameters
* **product** (`Product`) - The product object to download.
* **path** (`str`) - The output directory for the downloaded files.
* **file_types** (`ProductFileType`) - Optional. Specifies the types of product files to download. Defaults to `ProductFileType.ALL`.
* **raise_on_failure** (`bool`) - Optional. If True, raises an exception on failure. Defaults to True.
```

--------------------------------

### Access Local Product Paths via MEP

Source: https://vitobelgium.github.io/terracatalogueclient/usage.html

Queries products and retrieves their local paths by setting `accessedFrom="MEP"`. This is useful in environments like Terrascope Notebooks or VM.

```python
products = catalogue.get_products(
    collection="urn:eop:VITO:TERRASCOPE_S2_FAPAR_V2",
    start="2021-02-01",
    end="2021-02-28",
    tileId="31UGS",
    resolution=20,
    accessedFrom="MEP"  # get local path
)

# href of the product file now contains the local path
local_paths = [pf.href for p in products for pf in p.data]


```

--------------------------------

### Load All Products into Memory

Source: https://vitobelgium.github.io/terracatalogueclient/usage.html

Converts the iterator returned by `get_products()` into a list to allow multiple iterations, loading all results into memory.

```python
>>> products_list = list(catalogue.get_products(...))

```

--------------------------------

### CatalogueConfig.from_file

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Retrieves a CatalogueConfig object directly from a specified configuration file.

```APIDOC
## CatalogueConfig.from_file

### Description
Get a catalogue configuration object from a configuration file.

### Method
static

### Parameters
#### Path Parameters
* **path** (str) - Required - Path of the catalogue .ini configuration file.

### Response
#### Success Response (CatalogueConfig)
Returns: CatalogueConfig object
```

--------------------------------

### Build Product object from JSON

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Constructs a Product object from a GeoJSON feature dictionary. It parses product details including acquisition dates, and file links for data, related resources, and previews.

```python
@staticmethod
def _build_product(feature: dict) -> Product:
    """Build product object from the JSON response.
    :param feature: feature as a JSON dict
    """
    id = feature["id"]
    title = feature["properties"]["title"]
    geometry = shape(feature["geometry"])
    bbox = feature["bbox"]

    # get first acquisitionParameters block, if available
    acquisitionParameters = next(
        iter(
            [
                i["acquisitionParameters"]
                for i in feature["properties"]["acquisitionInformation"]
                if "acquisitionParameters" in i
            ]
        ),
        None,
    )
    beginningDateTime = (
        _parse_date(acquisitionParameters["beginningDateTime"]) 
        if acquisitionParameters and "beginningDateTime" in acquisitionParameters
        else None
    )
    endingDateTime = (
        _parse_date(acquisitionParameters["endingDateTime"]) 
        if acquisitionParameters and "endingDateTime" in acquisitionParameters
        else None
    )

    # build product files
    links = feature["properties"]["links"]
    data = Catalogue._build_files(links["data"]) if "data" in links else []
    related = Catalogue._build_files(links["related"]) if "related" in links else []
    previews = (
        Catalogue._build_files(links["previews"]) if "previews" in links else []
    )
    alternates = 
```

--------------------------------

### download_file

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Downloads a single product file from a given URL. It supports HTTP(S) and S3 protocols. For HTTP(S) downloads, it calls `_download_file_http`. For S3, it calls `_download_file_s3`.

```APIDOC
## download_file

### Description
Download a single product file. Determines the appropriate download protocol (HTTP/S3) based on the file's href and initiates the download.

### Method
`download_file(product_file: ProductFile, path: str)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **product_file** (ProductFile) - Required - The product file object to download.
* **path** (str) - Required - The output directory to write the file to.

### Request Example
```python
# Example usage (assuming 'client' is an instance of TerracatalogueClient, 'file_to_download' is a ProductFile object)
# client.download_file(file_to_download, "/path/to/save/files")
```

### Response
None

### Error Handling
- Raises a `ProductDownloadException` if the protocol is not supported or if the href is not a downloadable path.
```

--------------------------------

### download_product

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Downloads a single product, including all files associated with it that match the specified file types. It iterates through the product's files and calls `download_file` for each.

```APIDOC
## download_product

### Description
Download a single product. This will download all files belonging to the given product matching the provided file types.

### Method
`download_product(product: Product, path: str, file_types: ProductFileType = ProductFileType.ALL, raise_on_failure: bool = True)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **product** (Product) - Required - The product to download.
* **path** (str) - Required - The output directory to write files to.
* **file_types** (ProductFileType) - Optional - The type of product files to download. Defaults to `ProductFileType.ALL`.
* **raise_on_failure** (bool) - Optional - If True, raises an exception on a download failure. Defaults to True.

### Request Example
```python
# Example usage (assuming 'client' is an instance of TerracatalogueClient, 'single_product' is a Product object)
# client.download_product(single_product, "/path/to/save/files", file_types=ProductFileType.PREVIEWS)
```

### Response
None

### Error Handling
- Raises a `ConnectionError` if encountered during file download and `raise_on_failure` is True.
```

--------------------------------

### ProductFile Class Definition

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Represents a file associated with a product, including its URI, length, title, type, and category.

```python
class ProductFile:
    """
    File that belongs to a product.

    :ivar href: URI locator of the product file
    :vartype href: str
    :ivar length: content length in bytes
    :vartype length: Optional[int]
    :ivar title: title of the product file
    :vartype title: Optional[str]
    :ivar type: content type
    :vartype type: Optional[str]
    :ivar category: category, only applicable for previews or related files
    :vartype category: Optional[str]
    """

    def __init__(
        self,
        href: str,
        length: Optional[int],
        title: Optional[str] = None,
        type: Optional[str] = None,
        category: Optional[str] = None,
    ):
        self.href = href
        self.length = length
        self.title = title
        self.type = type
        self.category = category

    def __str__(self):
        return self.href

    def get_protocol(self):
        return self.href[: self.href.find("://")].lower()
```

--------------------------------

### download_products

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Downloads multiple products and their associated files, with options for file types, forcing downloads, and error handling.

```APIDOC
## download_products(products, path, file_types=ProductFileType.ALL, force=False, raise_on_failure=True)

Downloads a list of products and their files, matching the specified file types. Supports forcing downloads and controlling error exceptions.

### Parameters
* **products** (`Iterable`[`Product`]) - An iterable of product objects to download.
* **path** (`str`) - The output directory for the downloaded files.
* **file_types** (`ProductFileType`) - Optional. Specifies the types of product files to download. Defaults to `ProductFileType.ALL`.
* **force** (`bool`) - Optional. Skips download confirmation if True. Defaults to False.
* **raise_on_failure** (`bool`) - Optional. If True, raises an exception on failure. Defaults to True.
```

--------------------------------

### CatalogueConfig.from_environment

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Retrieves a CatalogueConfig object from a predefined environment. Allows overriding with values from a specified configuration file.

```APIDOC
## CatalogueConfig.from_environment

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

### Method
static

### Parameters
#### Path Parameters
* **environment** (CatalogueEnvironment) - Required - The pre-defined environment.
* **path** (str) - Optional - Optional path of the catalogue .ini configuration file containing values to override the pre-defined environment config.

### Response
#### Success Response (CatalogueConfig)
Returns: CatalogueConfig object
```

--------------------------------

### ProductFile Class

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Represents a single file associated with a product. It includes the file's URI, length, title, type, and category.

```APIDOC
## Class ProductFile

### Description
Represents a file that belongs to a product. It contains the Uniform Resource Identifier (URI) for the file, its size, title, content type, and category.

### Attributes
- **href** (str): The URI locator of the product file.
- **length** (Optional[int]): The content length of the file in bytes. Optional, as it might not always be available.
- **title** (Optional[str]): The title of the product file. Optional.
- **type** (Optional[str]): The content type of the file (e.g., 'application/json'). Optional.
- **category** (Optional[str]): The category of the file, applicable for previews or related files. Optional.

### Methods
- **__init__(self, href: str, length: Optional[int], title: Optional[str] = None, type: Optional[str] = None, category: Optional[str] = None)**: Initializes a new ProductFile object.
- **__str__(self)**: Returns the string representation of the ProductFile, which is its `href`.
- **get_protocol(self)**: Returns the protocol of the file's URI (e.g., 'http', 'https').
```

--------------------------------

### HTTP File Download

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Downloads a single product file over HTTP. Assumes the product file's href is a valid HTTP URL and checks authorization before downloading.

```python
def _download_file_http(self, product_file: ProductFile, path: str):
        """Download a single product file over HTTP.
        Assumes that the href in the product file contains a valid HTTP address.

        :param product_file: product file to download
        :param path: output directory to write the file to
        """
        if not self._is_authorized_to_download_http(product_file):
            raise ProductDownloadException(

```

--------------------------------

### Download Products via S3

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Downloads products using the S3 access method. Ensure S3 endpoint and credentials are configured. The 'accessedFrom="S3"' parameter specifies the access method during product querying.

```python
products = catalogue.get_products(
    collection=collection,
    start="2021-01-01",
    end="2021-02-01",
    tileId="31UES",
    accessedFrom="S3"
)
# download automatically selects the access method specified when querying the products
catalogue.download_products(products, path)
```

--------------------------------

### Query Products by Collection, Date, and Tile ID

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Retrieve products for a specific collection, date range, and tile identifier. The get_products method returns an iterator.

```python
import datetime as dt

products = catalogue.get_products(
    "urn:eop:VITO:TERRASCOPE_S2_NDVI_V2",
    start=dt.date(2020, 5, 1),
    end=dt.date(2020, 6, 1),
    tileId="31UGS"
)
for product in products:
    print(product.title)
```

--------------------------------

### Download Specific Product File Types

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Downloads only specific types of product files, such as data files and related resources, using the 'file_types' parameter with enum flags. Combine flags using the '|' operator.

```python
catalogue.download_product(product, path, ProductFileType.DATA | ProductFileType.RELATED)
```

--------------------------------

### Authenticate Interactively

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Initiates an interactive authentication flow, opening a browser for user sign-in. Use when user interaction is possible.

```python
catalogue.authenticate()
```

--------------------------------

### Download Single Product

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Downloads all files for a single product, filtering by specified file types. It iterates through matching product files and calls download_file for each.

```python
def download_product(
        self,
        product: Product,
        path: str,
        file_types: ProductFileType = ProductFileType.ALL,
        raise_on_failure: bool = True,
    ):
        """Download a single product. This will download all files belonging to the given product.

        :param product: product to download
        :param path: output directory to write files to
        :param file_types: type of product files to download
        :param raise_on_failure: raise an exception on a failure or silently continue
        """
        for product_file in self._get_product_files_matching_file_types(
            product, file_types
        ):
            try:
                self.download_file(product_file, self._get_product_dir(path, product))
            except ConnectionError as e:
                logger.error(e)
                if raise_on_failure:
                    raise e
```

--------------------------------

### Download Specific Product File Types

Source: https://vitobelgium.github.io/terracatalogueclient/usage.html

Downloads only specified types of product files (e.g., data and related resources) using the `file_types` parameter with `ProductFileType` enum flags.

```python
>>> catalogue.download_product(product, path, ProductFileType.DATA | ProductFileType.RELATED)

```

--------------------------------

### Configuration

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/api.rst.txt

This section covers the API methods related to the configuration of the TerraCatalogueClient. It allows users to manage settings and parameters for the client's operation.

```APIDOC
## Configuration API

### Description
Provides methods for configuring the TerraCatalogueClient. Users can set up and manage client-specific settings, such as API endpoints or authentication credentials.

### Methods
This module exposes methods for configuration. Refer to the automodule documentation for specific method signatures and parameters.

### Example Usage
```python
# Example of how to use the configuration methods
# (Specific methods and usage depend on the automodule content)
from terracatalogueclient import config

# Assuming config is initialized or methods are available
# config.set_api_key('your_api_key')
# current_settings = config.get_settings()
```
```

--------------------------------

### Catalogue, Collections, and Products

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/api.rst.txt

This section details the API methods for interacting with catalogues, collections, and products. It covers functionalities for retrieving, creating, updating, and deleting these resources.

```APIDOC
## Catalogue, Collections, and Products API

### Description
Provides methods to interact with catalogues, collections, and products. Users can perform operations such as listing catalogues, retrieving collection details, and managing product information.

### Methods
This module exposes various methods for catalogue management. Refer to the automodule documentation for specific method signatures and parameters.

### Example Usage
```python
# Example of how to use the catalogue client methods
# (Specific methods and usage depend on the automodule content)
from terracatalogueclient import client

# Assuming client is initialized
# catalogue_data = client.list_catalogues()
# collection_data = client.get_collection('collection_id')
# product_data = client.get_product('product_id')
```
```

--------------------------------

### Catalogue.authenticate

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Authenticates to the catalogue interactively by opening a browser window for the sign-in procedure. This method is only supported if the catalogue endpoint allows for interactive authentication.

```APIDOC
## Catalogue.authenticate

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

### Method
```python
def authenticate(self) -> "Catalogue":
```

### Parameters
None

### Returns
- **Catalogue**: The catalogue object after successful authentication.
```

--------------------------------

### get_products

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Retrieves products matching a query within a specified collection, with extensive filtering options.

```APIDOC
## 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)

Fetches products from a collection based on various criteria including temporal range, spatial extent, product details, orbit information, and cloud cover. Supports limiting the number of results and additional query parameters.

### Parameters
* **collection** (`str`) - The collection to query.
* **start** (`Union`[`str`, `date`, `datetime`, `None`]) - Optional. Start of the temporal interval for searching.
* **end** (`Union`[`str`, `date`, `datetime`, `None`]) - Optional. End of the temporal interval for searching.
* **bbox** (`Union`[`str`, `List`[`Union`[`int`, `float`]], `Dict`[`str`, `Union`[`int`, `float`]], `None`]) - Optional. Geographic bounding box (west, south, east, north) as a string, list, or dictionary.
* **geometry** (`Union`[`str`, `BaseGeometry`, `None`]) - Optional. Geometry as a WKT string or Shapely geometry object.
* **title** (`Optional`[`str`]) - Optional. Title of the product to search for.
* **productType** (`Optional`[`str`]) - Optional. The type of product.
* **relativeOrbitNumber** (`Union`[`int`, `str`, `None`]) - Optional. The relative acquisition orbit number.
* **orbitDirection** (`Optional`[`str`]) - Optional. The acquisition orbit direction.
* **cloudCover** (`Union`[`Tuple`[`Union`[`float`, `int`, `None`], `Union`[`float`, `int`, `None`]], `float`, `int`, `str`, `None`]) - Optional. Maximum cloud cover percentage, an interval, or a set/string of percentages.
* **tileId** (`Optional`[`str`]) - Optional. The tile ID.
* **productGroupId** (`Optional`[`str`]) - Optional. The product group ID.
* **publicationDate** (`Optional`[`str`]) - Optional. The publication date.
* **modificationDate** (`Optional`[`str`]) - Optional. The modification date.
* **accessedFrom** (`Optional`[`str`]) - Optional. Filter by access origin.
* **limit** (`Optional`[`int`]) - Optional. The maximum number of products to return.
* **kwargs** - Additional query parameters.
```

--------------------------------

### Query Collections by Platform

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Filter collections based on the acquisition platform, such as 'SENTINEL-1'.

```python
collections = catalogue.get_collections(platform="SENTINEL-1")
```

--------------------------------

### authenticate

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Authenticates to the catalogue interactively by opening a browser window for the sign-in procedure.

```APIDOC
## authenticate()

Authenticates to the catalogue in an interactive manner. A browser window will open to manage the sign-in process.

### Returns
* `Catalogue` - The authenticated catalogue object.
```

--------------------------------

### Check HTTP Download Authorization

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Checks if the authenticated user is authorized to download a product file via HTTP. Performs a HEAD request to the product file's URL.

```python
def _is_authorized_to_download_http(self, product_file: ProductFile) -> bool:
        """Check if the authenticated user has authorization to download the product file.
        If the user is not authenticated, a redirect will take place.

        :param product_file: product file
        """
        r = self._session_download.head(product_file.href, timeout=_DOWNLOAD_TIMEOUT)
        return r.ok
```

--------------------------------

### Authenticate Catalogue Client

Source: https://vitobelgium.github.io/terracatalogueclient/_sources/usage.rst.txt

Authenticate the Catalogue client to access protected collections or download products. This method opens a browser for user login.

```python
from terracatalogueclient import Catalogue
catalogue = Catalogue().authenticate()  # authenticated catalogue
```

--------------------------------

### Convert API Parameters

Source: https://vitobelgium.github.io/terracatalogueclient/_modules/terracatalogueclient/client.html

Converts various parameters for API requests, including date formatting, interval string creation, geometry conversion to WKT, bounding box formatting, and cloud cover range conversion.

```python
@staticmethod
def _convert_parameters(params):
        parameter_time = ["start", "end"]
        parameter_time_interval = ["publicationDate", "modificationDate"]

        for p in parameter_time:
            if p in params:
                params[p] = _date_to_str(params[p])

        for p in parameter_time_interval:
            if p in params:
                if type(params[p]) == tuple:
                    params[p] = _tuple_to_interval_str(params[p], p, _date_to_str)

        if "geometry" in params:
            p = "geometry"
            if isinstance(params[p], str):
                pass
            elif isinstance(params[p], BaseGeometry):
                params[p] = wkt.dumps(params[p], trim=True)

        if "bbox" in params:
            p = "bbox"
            if isinstance(params[p], str):
                pass
            elif isinstance(params[p], list):
                params[p] = ",".join(str(i) for i in params[p])
            elif isinstance(params[p], dict):
                params[
                    p
                ] = f"{params[p]['west']},{params[p]['south']},{params[p]['east']},{params[p]['north']}"

        if "cloudCover" in params:
            p = "cloudCover"
            if type(params[p]) == tuple:
                params[p] = _tuple_to_interval_str(params[p], p, str)
            elif isinstance(params[p], int) or isinstance(params[p], float):
                params[p] = f"{params[p]}]"

        return params
```

--------------------------------

### Search Catalogue, Collections, and Products

Source: https://vitobelgium.github.io/terracatalogueclient/api.html

Allows searching for catalogue items, collections, and products with various filtering options. It returns an iterator of Product objects.

```APIDOC
## Search Catalogue, Collections, and Products

### Description
This method allows users to search for catalogue items, collections, and products. It supports filtering by tile ID, product group ID, publication date, modification date, and access origin. Additional query parameters can be passed as keyword arguments. The method returns an iterator yielding `Product` objects.

### Parameters
#### Query Parameters
- **tileId** (string) - Optional - tile identifier
- **productGroupId** (string) - Optional - 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]) - Optional - date of publication, as a date range or a string
- **modificationDate** (Union[Tuple[Union[date, datetime, str, None], Union[date, datetime, str, None]], str, None]) - Optional - date of modification, as a date range or a string
- **accessedFrom** (string) - Optional - information on the origin of the request
- **limit** (integer) - Optional - limit the number of requested products
- ****kwargs** - Additional query parameters can be provided as keyword arguments.

### Return Type
`Iterator[Product]`
```
Tokens:
Raw