Client

`cdse.client.CDSEClient`

Main client for Copernicus Data Space Ecosystem.

This is the primary interface for searching and downloading satellite data from CDSE. It combines authentication, catalog search, and download functionality into a simple API.

Example

client = CDSEClient( ... client_id="your-client-id", ... client_secret="your-client-secret" ... )

Search for products

products = client.search( ... bbox=[9.0, 45.0, 9.5, 45.5], ... start_date="2024-01-01", ... end_date="2024-01-31", ... collection="sentinel-2-l2a", ... cloud_cover_max=20 ... )

Download products

for product in products: ... client.download(product)

`catalog: Catalog` `property`

Get the catalog search client (lazy initialization).

`downloader: Downloader` `property`

Get the downloader client (lazy initialization).

`init(client_id: Optional[str] = None, client_secret: Optional[str] = None, output_dir: str = '.')`

Initialize the CDSE client.

Parameters:

Name	Type	Description	Default
`client_id`	`Optional[str]`	OAuth2 client ID. If not provided, reads from CDSE_CLIENT_ID environment variable.	`None`
`client_secret`	`Optional[str]`	OAuth2 client secret. If not provided, reads from CDSE_CLIENT_SECRET environment variable.	`None`
`output_dir`	`str`	Default directory for downloaded files.	`'.'`

Raises:

Type	Description
`AuthenticationError`	If credentials are not provided.

`search(bbox: list[float], start_date: str, end_date: str, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, **kwargs: Any) -> list[Product]`

Search for products in the CDSE catalog.

Parameters:

Name	Type	Description	Default
`bbox`	`list[float]`	Bounding box [min_lon, min_lat, max_lon, max_lat]	required
`start_date`	`str`	Start date in ISO format (YYYY-MM-DD)	required
`end_date`	`str`	End date in ISO format (YYYY-MM-DD)	required
`collection`	`str`	Collection name (default: sentinel-2-l2a)	`'sentinel-2-l2a'`
`cloud_cover_max`	`float`	Maximum cloud coverage percentage (0-100)	`100.0`
`limit`	`int`	Maximum number of results	`10`
`**kwargs`	`Any`	Additional STAC API parameters	`{}`

Returns:

Type	Description
`list[Product]`	List of Product objects matching the search criteria

Raises:

Type	Description
`ValidationError`	If input parameters are invalid
`CatalogError`	If the API request fails

`search_by_point(lon: float, lat: float, start_date: str, end_date: str, buffer_km: float = 10.0, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, **kwargs: Any) -> list[Product]`

Search for products by geographic point.

Parameters:

Name	Type	Description	Default
`lon`	`float`	Longitude (-180 to 180)	required
`lat`	`float`	Latitude (-90 to 90)	required
`start_date`	`str`	Start date in ISO format (YYYY-MM-DD)	required
`end_date`	`str`	End date in ISO format (YYYY-MM-DD)	required
`buffer_km`	`float`	Search radius in kilometers (default: 10)	`10.0`
`collection`	`str`	Collection name	`'sentinel-2-l2a'`
`cloud_cover_max`	`float`	Maximum cloud coverage percentage	`100.0`
`limit`	`int`	Maximum number of results	`10`
`**kwargs`	`Any`	Additional STAC API parameters	`{}`

Returns:

Type	Description
`list[Product]`	List of Product objects

`download(product: Product, output_dir: Optional[str] = None, filename: Optional[str] = None, progress: bool = True) -> Path`

Download a single product.

Parameters:

Name	Type	Description	Default
`product`	`Product`	Product to download	required
`output_dir`	`Optional[str]`	Override output directory	`None`
`filename`	`Optional[str]`	Custom filename (default: product_name.zip)	`None`
`progress`	`bool`	Show progress bar	`True`

Returns:

Type	Description
`Path`	Path to the downloaded file

Raises:

Type	Description
`DownloadError`	If download fails

`download_all(products: list[Product], output_dir: Optional[str] = None, skip_existing: bool = True, progress: bool = True, parallel: bool = False, max_workers: int = 4) -> list[Path]`

Download multiple products.

Parameters:

Name	Type	Description	Default
`products`	`list[Product]`	List of products to download	required
`output_dir`	`Optional[str]`	Override output directory	`None`
`skip_existing`	`bool`	Skip already downloaded products	`True`
`progress`	`bool`	Show progress bars	`True`
`parallel`	`bool`	Enable parallel downloads for faster performance	`False`
`max_workers`	`int`	Number of parallel download workers (when parallel=True)	`4`

Returns:

Type	Description
`list[Path]`	List of paths to downloaded files

`search_by_name(name: str, exact: bool = True) -> Optional[Product]`

Search for a product by its name.

Parameters:

Name	Type	Description	Default
`name`	`str`	Product name (e.g., S2A_MSIL2A_20240115...)	required
`exact`	`bool`	If True, require exact match. If False, use prefix match.	`True`

Returns:

Type	Description
`Optional[Product]`	Product if found, None otherwise

Raises:

Type	Description
`CatalogError`	If API request fails

`search_by_id(product_id: str) -> Optional[Product]`

Search for a product by its UUID.

Parameters:

Name	Type	Description	Default
`product_id`	`str`	Product UUID	required

Returns:

Type	Description
`Optional[Product]`	Product if found, None otherwise

Raises:

Type	Description
`CatalogError`	If API request fails

`download_with_checksum(product: Product, output_dir: Optional[str] = None, progress: bool = True) -> Path`

Download a product and verify its checksum.

Parameters:

Name	Type	Description	Default
`product`	`Product`	Product to download	required
`output_dir`	`Optional[str]`	Override output directory	`None`
`progress`	`bool`	Show progress bar	`True`

Returns:

Type	Description
`Path`	Path to downloaded file (verified)

Raises:

Type	Description
`DownloadError`	If download or checksum verification fails

`search_by_city(city_name: str, start_date: str, end_date: str, buffer_km: float = 15.0, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, use_predefined: bool = False, geocoding_timeout: float = 10.0, geocoding_user_agent: str = 'cdse-client', **kwargs: Any) -> list[Product]`

Search for products over a city.

This method geocodes a city name to coordinates and searches for satellite products within a buffer around the city center.

Parameters:

Name	Type	Description	Default
`city_name`	`str`	Name of the city (e.g., "Milano, Italia", "Paris, France")	required
`start_date`	`str`	Start date in ISO format (YYYY-MM-DD)	required
`end_date`	`str`	End date in ISO format (YYYY-MM-DD)	required
`buffer_km`	`float`	Buffer around city center in kilometers (default: 15)	`15.0`
`collection`	`str`	Collection name (default: sentinel-2-l2a)	`'sentinel-2-l2a'`
`cloud_cover_max`	`float`	Maximum cloud coverage percentage (0-100)	`100.0`
`limit`	`int`	Maximum number of results	`10`
`use_predefined`	`bool`	Use predefined city bbox instead of geocoding. Useful as fallback when geopy is not installed.	`False`
`geocoding_timeout`	`float`	Network timeout in seconds for live geocoding.	`10.0`
`geocoding_user_agent`	`str`	User agent for Nominatim geocoding.	`'cdse-client'`
`**kwargs`	`Any`	Additional STAC API parameters	`{}`

Returns:

Type	Description
`list[Product]`	List of Product objects matching the search criteria

Raises:

Type	Description
`ImportError`	If geopy is not installed and use_predefined is False
`ValueError`	If city is not found
`CatalogError`	If the API request fails

Example

products = client.search_by_city( ... city_name="Roma, Italia", ... start_date="2024-08-01", ... end_date="2024-08-31", ... cloud_cover_max=20 ... )

`get_collections() -> dict`

Get available data collections.

Returns:

Type	Description
`dict`	Dictionary mapping collection IDs to descriptions.

`refresh_auth() -> None`

Refresh authentication token.

Call this if you need to refresh the token before it expires.

`to_dataframe(products: list[Product]) -> pd.DataFrame` `staticmethod`

Convert products to Pandas DataFrame.

Requires pandas to be installed: pip install pandas

Parameters:

Name	Type	Description	Default
`products`	`list[Product]`	List of Product objects from search results	required

Returns:

Type	Description
`DataFrame`	pandas.DataFrame with product metadata, indexed by product ID

Raises:

Type	Description
`ImportError`	If pandas is not installed

Example

products = client.search(...) df = client.to_dataframe(products) df_sorted = df.sort_values('cloud_cover') df.head()

`to_geojson(products: list[Product]) -> dict[str, Any]` `staticmethod`

Convert products to GeoJSON FeatureCollection.

Parameters:

Name	Type	Description	Default
`products`	`list[Product]`	List of Product objects from search results	required

Returns:

Type	Description
`dict[str, Any]`	GeoJSON FeatureCollection dictionary with footprints

Example

products = client.search(...) geojson = client.to_geojson(products) with open("footprints.geojson", "w") as f: ... json.dump(geojson, f)

`to_geodataframe(products: list[Product]) -> gpd.GeoDataFrame` `staticmethod`

Convert products to GeoPandas GeoDataFrame.

Requires geopandas: pip install geopandas

Parameters:

Name	Type	Description	Default
`products`	`list[Product]`	List of Product objects from search results	required

Returns:

Type	Description
`GeoDataFrame`	geopandas.GeoDataFrame with metadata and geometry

Raises:

Type	Description
`ImportError`	If geopandas is not installed

Example

products = client.search(...) gdf = client.to_geodataframe(products) gdf.plot() # Visualize footprints

`get_products_size(products: list[Product]) -> float` `staticmethod`

Calculate total size of products in GB.

Parameters:

Name	Type	Description	Default
`products`	`list[Product]`	List of Product objects	required

Returns:

Type	Description
`float`	Total size in gigabytes

Example

products = client.search(...) size_gb = client.get_products_size(products) print(f"Total: {size_gb:.2f} GB")

`download_quicklook(product: Product, output_dir: Optional[str] = None) -> Path`

Download quicklook (preview) image for a product.

Parameters:

Name	Type	Description	Default
`product`	`Product`	Product to get quicklook for	required
`output_dir`	`Optional[str]`	Output directory (default: client output_dir)	`None`

Returns:

Type	Description
`Path`	Path to downloaded quicklook image

Raises:

Type	Description
`DownloadError`	If quicklook download fails

`download_all_quicklooks(products: list[Product], output_dir: Optional[str] = None, parallel: bool = True, max_workers: int = 4) -> list[Path]`

Download quicklooks for multiple products.

Parameters:

Name	Type	Description	Default
`products`	`list[Product]`	List of products	required
`output_dir`	`Optional[str]`	Output directory	`None`
`parallel`	`bool`	Enable parallel downloads	`True`
`max_workers`	`int`	Number of parallel workers	`4`

Returns:

Type	Description
`list[Path]`	List of paths to downloaded quicklook images

Client

cdse.client.CDSEClient

Search for products

Download products

catalog: Catalog property

downloader: Downloader property

__init__(client_id: Optional[str] = None, client_secret: Optional[str] = None, output_dir: str = '.')

search(bbox: list[float], start_date: str, end_date: str, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, **kwargs: Any) -> list[Product]

search_by_point(lon: float, lat: float, start_date: str, end_date: str, buffer_km: float = 10.0, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, **kwargs: Any) -> list[Product]

download(product: Product, output_dir: Optional[str] = None, filename: Optional[str] = None, progress: bool = True) -> Path

download_all(products: list[Product], output_dir: Optional[str] = None, skip_existing: bool = True, progress: bool = True, parallel: bool = False, max_workers: int = 4) -> list[Path]

search_by_name(name: str, exact: bool = True) -> Optional[Product]

search_by_id(product_id: str) -> Optional[Product]

download_with_checksum(product: Product, output_dir: Optional[str] = None, progress: bool = True) -> Path

get_collections() -> dict

refresh_auth() -> None

to_dataframe(products: list[Product]) -> pd.DataFrame staticmethod

to_geojson(products: list[Product]) -> dict[str, Any] staticmethod

to_geodataframe(products: list[Product]) -> gpd.GeoDataFrame staticmethod

get_products_size(products: list[Product]) -> float staticmethod

download_quicklook(product: Product, output_dir: Optional[str] = None) -> Path

download_all_quicklooks(products: list[Product], output_dir: Optional[str] = None, parallel: bool = True, max_workers: int = 4) -> list[Path]

`cdse.client.CDSEClient`

`catalog: Catalog` `property`

`downloader: Downloader` `property`

`init(client_id: Optional[str] = None, client_secret: Optional[str] = None, output_dir: str = '.')`

`search(bbox: list[float], start_date: str, end_date: str, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, **kwargs: Any) -> list[Product]`

`search_by_point(lon: float, lat: float, start_date: str, end_date: str, buffer_km: float = 10.0, collection: str = 'sentinel-2-l2a', cloud_cover_max: float = 100.0, limit: int = 10, **kwargs: Any) -> list[Product]`

`download(product: Product, output_dir: Optional[str] = None, filename: Optional[str] = None, progress: bool = True) -> Path`

`download_all(products: list[Product], output_dir: Optional[str] = None, skip_existing: bool = True, progress: bool = True, parallel: bool = False, max_workers: int = 4) -> list[Path]`

`search_by_name(name: str, exact: bool = True) -> Optional[Product]`

`search_by_id(product_id: str) -> Optional[Product]`

`download_with_checksum(product: Product, output_dir: Optional[str] = None, progress: bool = True) -> Path`

`get_collections() -> dict`

`refresh_auth() -> None`

`to_dataframe(products: list[Product]) -> pd.DataFrame` `staticmethod`

`to_geojson(products: list[Product]) -> dict[str, Any]` `staticmethod`

`to_geodataframe(products: list[Product]) -> gpd.GeoDataFrame` `staticmethod`

`get_products_size(products: list[Product]) -> float` `staticmethod`

`download_quicklook(product: Product, output_dir: Optional[str] = None) -> Path`

`download_all_quicklooks(products: list[Product], output_dir: Optional[str] = None, parallel: bool = True, max_workers: int = 4) -> list[Path]`