API Reference

This section provides detailed documentation for all classes and functions in Φ-Down.

API Documentation

Main Classes and Functions

Search Module

class phidown.search.CopernicusDataSearcher[source]

Bases: object

__init__()[source]

Initialize the CopernicusDataSearcher. Configuration is loaded from the default path. Call query_by_filter() to set search parameters before executing a query.

query_by_filter(base_url='https://catalogue.dataspace.copernicus.eu/odata/v1/Products', collection_name='SENTINEL-1', product_type=None, orbit_direction=None, cloud_cover_threshold=None, attributes=None, aoi_wkt=None, start_date=None, end_date=None, top=1000, count=False, order_by='ContentDate/Start desc', burst_mode=False, burst_id=None, absolute_burst_id=None, swath_identifier=None, parent_product_name=None, parent_product_type=None, parent_product_id=None, datatake_id=None, relative_orbit_number=None, operational_mode=None, polarisation_channels=None, platform_serial_identifier=None)[source]

Set and validate search parameters for the Copernicus data query.

Parameters:

  • base_url (str) – The base URL for the OData API.

  • collection_name (str, optional) – Name of the collection to search. Defaults to ‘SENTINEL-1’.

  • product_type (str, optional) – Type of product to filter. Defaults to None.

  • orbit_direction (str, optional) – Orbit direction to filter (e.g., ‘ASCENDING’, ‘DESCENDING’). Defaults to None.

  • cloud_cover_threshold (float, optional) – Maximum cloud cover percentage to filter. Defaults to None.

  • attributes (Dict[str, Union[str, int, float]], optional) – Additional attributes for filtering. Defaults to None.

  • aoi_wkt (str, optional) – Area of Interest in WKT format. Defaults to None.

  • start_date (str, optional) – Start date for filtering (ISO 8601 format). Defaults to None.

  • end_date (str, optional) – End date for filtering (ISO 8601 format). Defaults to None.

  • top (int, optional) – Maximum number of results to retrieve. Defaults to 1000.

  • count (bool, optional) – Whether to include count of results. Defaults to False.

  • order_by (str, optional) – Field and direction to order results by. Defaults to “ContentDate/Start desc”.

  • burst_mode (bool, optional) – Enable Sentinel-1 SLC Burst mode searching. Defaults to False.

  • burst_id (int, optional) – Burst ID to filter (burst mode only). Defaults to None.

  • absolute_burst_id (int, optional) – Absolute Burst ID to filter (burst mode only). Defaults to None.

  • swath_identifier (str, optional) – Swath identifier (e.g., ‘IW1’, ‘IW2’) (burst mode only). Defaults to None.

  • parent_product_name (str, optional) – Parent product name (burst mode only). Defaults to None.

  • parent_product_type (str, optional) – Parent product type (burst mode only). Defaults to None.

  • parent_product_id (str, optional) – Parent product ID (burst mode only). Defaults to None.

  • datatake_id (int, optional) – Datatake ID (burst mode only). Defaults to None.

  • relative_orbit_number (int, optional) – Relative orbit number (burst mode only). Defaults to None.

  • operational_mode (str, optional) – Operational mode (e.g., ‘IW’, ‘EW’) (burst mode only). Defaults to None.

  • polarisation_channels (str, optional) – Polarisation channels (e.g., ‘VV’, ‘VH’) (burst mode only). Defaults to None.

  • platform_serial_identifier (str, optional) – Platform serial identifier (e.g., ‘A’, ‘B’) (burst mode only). Defaults to None.

Return type:

None

execute_query()[source]

Execute the query and retrieve data

query_by_name(product_name)[source]

Query Copernicus data by a specific product name. The results (DataFrame) are stored in self.df.

Parameters:

product_name (str) – The exact name of the product to search for.

Returns:

A DataFrame containing the product details.

Returns an empty DataFrame if the product is not found or an error occurs.

Return type:

pd.DataFrame

Raises:

ValueError – If product_name is empty or not a string.

search_products_by_name_pattern(name_pattern, match_type, collection_name_filter=None, top=None, order_by=None)[source]

Searches for Copernicus products by a name pattern using ‘exact’, ‘contains’, ‘startswith’, or ‘endswith’. Optionally filters by a specific collection name or uses the instance’s current collection if set. The results (DataFrame) are stored in self.df.

Parameters:

  • name_pattern (str) – The pattern to search for in the product name.

  • match_type (str) – The type of match. Must be one of ‘exact’, ‘contains’, ‘startswith’, ‘endswith’.

  • collection_name_filter (str, optional) – Specific collection to filter this search by. If None, and self.collection_name (instance attribute) is set, self.collection_name will be used. If both are None, no collection filter based on collection name is applied for this specific search.

  • top (int, optional) – Maximum number of results. If None, uses self.top (instance default). Must be between 1 and 1000.

  • order_by (str, optional) – Field and direction to order results (e.g., ‘ContentDate/Start desc’). If None, uses self.order_by (instance default).

Returns:

DataFrame with product details. Empty if no match or error.

Return type:

pd.DataFrame

Raises:

ValueError – If name_pattern is empty, match_type is invalid, or effective ‘top’ is out of range. Also if ‘collection_name_filter’ is provided and is invalid.

display_results(columns=None, top_n=10)[source]

Display the query results with selected columns

download_product(eo_product_name, output_dir, config_file='.s5cfg', verbose=True, show_progress=True)[source]

Download the EO product using the downloader module.

Parameters:

  • eo_product_name (str) – Name of the EO product to download

  • output_dir (str) – Local output directory for downloaded files

  • config_file – Path to s5cmd configuration file

  • verbose – Whether to print download information

  • show_progress – Whether to show tqdm progress bar during download

Returns:

True if download was successful, False otherwise

Return type:

bool

Downloader Module

phidown.downloader.get_token(username, password)[source]

Acquire an access token from Copernicus Data Space Ecosystem.

This function authenticates with the CDSE identity service using username and password credentials to obtain a Keycloak access token for API access.

Parameters:

  • username (str) – CDSE account username.

  • password (str) – CDSE account password.

Returns:

The access token string to be used for authenticated API requests.

Return type:

str

Raises:

  • AssertionError – If username or password is empty.

  • requests.exceptions.HTTPError – If the authentication request fails.

Example

>>> token = get_token('myuser@example.com', 'mypassword')
Acquired keycloak token!
phidown.downloader.download_burst_on_demand(burst_id, token, output_dir)[source]

Download and save a Sentinel-1 burst product from CDSE.

This function requests on-demand processing of a single Sentinel-1 burst and downloads the resulting product as a ZIP file. The burst is identified by its UUID from the CDSE catalogue.

Parameters:

  • burst_id (str) – UUID of the burst to download from the CDSE catalogue.

  • token (str) – Keycloak access token obtained from get_token().

  • output_dir (Path) – Directory path where the burst ZIP file will be saved.

Raises:
Return type:

None

Example

>>> from pathlib import Path
>>> token = get_token('user@example.com', 'password')
>>> download_burst('12345678-1234-1234-1234-123456789abc', token, Path('./output'))
Processing burst...
Processing has been successful!
Saving output product...
Output product has been saved to: ./output/burst_12345678.zip
phidown.downloader.main()[source]

Main function for command-line usage of s5cmd_utils.

This function provides a simple CLI interface for downloading Sentinel-1 data from the Copernicus Data Space Ecosystem.

Return type:

None

Visualization Module

Interactive Tools Module