Skip to main content

cdse.CDSEBurstClient

Client for searching and downloading Sentinel-1 bursts from CDSE using the OData API.

Usage

Source

cdse.CDSEBurstClient(auth=None)

Implemented according to the CDSE API documentation [1].

Parameters

auth: CDSEAuth | None = None
Authentication instance. Required for downloading bursts.

References

  1. [1] Sentinel-1 SLC Burst API. Copernicus Data Space Ecosystem documentation. https://documentation.dataspace.copernicus.eu/APIs/Sentinel-1%20SLC%20Burst.html

Methods

Name Description
download_burst() Download a single Sentinel-1 burst by CDSE ID.
download_burst_from_s3() Download a single Sentinel-1 burst from CDSE S3.
search_bursts() Search for Sentinel-1 bursts matching specified criteria.

download_burst()

Download a single Sentinel-1 burst by CDSE ID.

Usage

Source

download_burst(cdse_id, save_path, *, progress=True)

Supports both local and remote (e.g. S3 via UPath) destinations.

Parameters
cdse_id: str

The burst’s CDSE product ID.

save_path: Path | UPath

Full destination path (including filename) for the downloaded file. Can be local or a remote UPath (e.g. S3). A remote file is first downloaded whole to the system temp directory and uploaded only once complete, so it needs local space for the burst (about 100 to 200 MB).

progress: bool = True
Whether to display download progress.
Returns
Path or UPath
Path of the downloaded file.
Raises
TypeError

If the client has no valid CDSEAuth instance.

requests.HTTPError

If the download request fails.

freezebase.errors.DownloadError
If the response is not a file, or redirects without a host or too often.

download_burst_from_s3()

Download a single Sentinel-1 burst from CDSE S3.

Usage

Source

download_burst_from_s3(
    save_path, *, parent_product_name, polarization, sub_swath, burst_id
)

Extracts the burst from the parent product with s3fs and rasterio, writing the result as a .zip to save_path (local or remote).

Parameters
save_path: Path | UPath

Full destination path (including filename) for the .zip. Can be local or a remote UPath (e.g. S3).

parent_product_name: str

Name of the parent Sentinel-1 product.

polarization: str

Polarization channels (e.g., ‘VV’, ‘VH’, ‘HH’, ‘HV’).

sub_swath: str

Sub-swath identifier (e.g., ‘IW1’, ‘IW2’, ‘IW3’).

burst_id: int
Relative burst ID within the swath.
Returns
Path or UPath
Path of the produced .zip file.
Raises
ValueError

If sub_swath is not a recognized sub-swath identifier.

BurstNotFoundError

If the parent product or the requested burst cannot be found.

BurstDownloadError

If the product’s annotation, calibration, noise, RFI or manifest file is malformed.

ConfigurationError
If the CDSE S3 credentials are not configured.

search_bursts()

Search for Sentinel-1 bursts matching specified criteria.

Usage

Source

search_bursts(filters=None, *, ascending=True, count=None)

Returns a single page of at most MAX_PAGE_SIZE items, the most the catalog serves per request. Request count to tell whether more bursts match than the page holds.

Parameters
filters: list[str] | None = None

List of OData filter expressions to apply.

ascending: bool = True

Whether to sort results by start time in ascending or descending order.

count: bool | None = None
Whether to include a total result count in the response.
Returns
CDSEResponse
Structured response with result metadata.
Raises
CatalogError
If the catalog cannot be reached, answers with an HTTP error, after retrying a transient one, or returns a malformed response. Its status_code is the HTTP status of an error response, such as 414 for a filter geometry with too many vertices.