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(config_path=None, **query_kwargs)[source]

Bases: object

__init__(config_path=None, **query_kwargs)[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.

  • 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.

If count=True and the total number of results exceeds the ‘top’ limit, this method will automatically paginate through all results using multiple requests with the $skip parameter, combining all results into a single DataFrame.

The returned DataFrame includes a ‘coverage’ column showing the percentage (0-100) of the AOI covered by each product’s footprint, if aoi_wkt is set and shapely is available.

Returns:

DataFrame containing all retrieved products with coverage column.

Return type:

pd.DataFrame

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

find_optimal_orbit(aoi_wkt=None, start_date=None, end_date=None, product_type='SLC', top=100)[source]

Find the optimal orbit direction and relative orbit for maximum AOI coverage.

This method searches both ascending and descending orbits and compares coverage to find the best configuration.

Parameters:

  • aoi_wkt (Optional[str]) – Area of Interest in WKT format. Uses self.aoi_wkt if None.

  • start_date (Optional[str]) – Start date in ISO 8601 format. Uses self.start_date if None.

  • end_date (Optional[str]) – End date in ISO 8601 format. Uses self.end_date if None.

  • product_type (str) – Product type to search (‘SLC’, ‘GRD’, etc.). Default ‘SLC’.

  • top (int) – Maximum results fetched per direction during orbit analysis.

Returns:

  • ascending: dict with orbits analysis for ascending

  • descending: dict with orbits analysis for descending

  • recommended: dict with optimal orbit_direction, relative_orbit, expected_coverage

Return type:

Dict containing

Example

>>> searcher = CopernicusDataSearcher()
>>> result = searcher.find_optimal_orbit(
...     aoi_wkt='POLYGON((10 45, 12 45, 12 46, 10 46, 10 45))',
...     start_date='2024-08-01T00:00:00Z',
...     end_date='2024-08-31T00:00:00Z'
... )
>>> print(f"Best: {result['recommended']['orbit_direction']} orbit {result['recommended']['relative_orbit']}")
find_optimal_bursts(aoi_wkt=None, start_date=None, end_date=None, polarisation='VV', orbit_direction=None, relative_orbit_number=None, preferred_subswath=None)[source]

Find optimal bursts covering the AOI with subswath preferences.

Preferences: - IW1 preferred over IW2, IW3 preferred last (lower incident angle) - If orbit_direction not specified: Descending for EU/America, Ascending for Asia/Australia

Parameters:

  • aoi_wkt (Optional[str]) – Area of Interest in WKT format. Uses self.aoi_wkt if None.

  • start_date (Optional[str]) – Start date in ISO 8601 format. Uses self.start_date if None.

  • end_date (Optional[str]) – End date in ISO 8601 format. Uses self.end_date if None.

  • polarisation (str) – Polarisation channel (‘VV’, ‘VH’, ‘HH’, ‘HV’). Default ‘VV’.

  • orbit_direction (Optional[str]) – Orbit direction (‘ASCENDING’ or ‘DESCENDING’). Auto-detected if None.

  • relative_orbit_number (Optional[int]) – Specific relative orbit to filter. None for all.

  • preferred_subswath (Optional[List[str]]) – List of subswaths in preference order. Default [‘IW1’, ‘IW2’, ‘IW3’].

Returns:

Optimized burst selection sorted by preference.

Return type:

pd.DataFrame

Example

>>> searcher = CopernicusDataSearcher()
>>> bursts = searcher.find_optimal_bursts(
...     aoi_wkt='POLYGON((10 45, 12 45, 12 46, 10 46, 10 45))',
...     start_date='2024-08-02T00:00:00Z',
...     end_date='2024-08-15T00:00:00Z',
...     polarisation='VV'
... )
compute_temporal_statistics(df=None)[source]

Compute temporal statistics for search results.

Parameters:

df (Optional[DataFrame]) – DataFrame with search results. Uses self.df if None.

Returns:

  • total_acquisitions: int

  • date_range: dict with start, end, span_days

  • temporal_gaps: dict with min_days, max_days, mean_days, median_days, std_days

  • acquisitions_by_month: dict

  • acquisitions_by_year: dict

Return type:

Dict containing

Example

>>> searcher = CopernicusDataSearcher()
>>> searcher.query_by_filter(...)
>>> searcher.execute_query()
>>> stats = searcher.compute_temporal_statistics()
>>> print(f"Mean revisit: {stats['temporal_gaps']['mean_days']:.1f} days")
plot_temporal_distribution(df=None, output_path=None, show=True, figsize=(14, 10))[source]

Create and save a plot of temporal distribution of acquisitions.

The plot includes: - Acquisition timeline scatter plot - Gap distribution histogram - Monthly acquisition counts - Cumulative acquisitions over time

Parameters:

  • df (Optional[DataFrame]) – DataFrame with search results. Uses self.df if None.

  • output_path (Optional[str]) – Path to save the plot. Auto-generated if None.

  • show (bool) – Whether to display the plot interactively.

  • figsize (Tuple[int, int]) – Figure size as (width, height) tuple.

Returns:

Path to the saved plot file, or None if not saved.

Return type:

str

Raises:

ImportError – If matplotlib is not installed.

Example

>>> searcher = CopernicusDataSearcher()
>>> searcher.query_by_filter(...)
>>> searcher.execute_query()
>>> searcher.plot_temporal_distribution(output_path='./temporal_plot.png')
download_bursts(df=None, output_dir='.', username=None, password=None, retry_count=3, verbose=True)[source]

Download burst products from a DataFrame.

This method handles CDSE authentication and downloads burst products via the on-demand processing API.

Parameters:

  • df (Optional[DataFrame]) – DataFrame with burst products to download. Uses self.df if None.

  • output_dir (str) – Directory to save downloaded bursts.

  • username (Optional[str]) – CDSE username. Required for burst downloads.

  • password (Optional[str]) – CDSE password. Required for burst downloads.

  • retry_count (int) – Number of retry attempts for failed downloads.

  • verbose (bool) – Whether to print progress information.

Returns:

  • downloaded: int count of successful downloads

  • failed: int count of failed downloads

  • details: list of dicts with download status per product

Return type:

Dict containing

Example

>>> searcher = CopernicusDataSearcher()
>>> searcher.query_by_filter(burst_mode=True, ...)
>>> df = searcher.execute_query()
>>> result = searcher.download_bursts(
...     df=df,
...     output_dir='./bursts',
...     username='your_cdse_username',
...     password='your_cdse_password'
... )
download_products(df=None, output_dir='.', config_file='.s5cfg', retry_count=3, validate=True, verbose=True, show_progress=True)[source]

Download multiple SLC/GRD products from a DataFrame.

This method downloads products via S3 using s5cmd with retry logic and optional validation.

Parameters:

  • df (Optional[DataFrame]) – DataFrame with products to download. Uses self.df if None.

  • output_dir (str) – Directory to save downloaded products.

  • config_file (str) – Path to s5cmd configuration file.

  • retry_count (int) – Number of retry attempts for failed downloads.

  • validate (bool) – Whether to validate downloaded files (check manifest.safe exists).

  • verbose (bool) – Whether to print progress information.

  • show_progress (bool) – Whether to show tqdm progress bar.

Returns:

  • downloaded: int count of successful downloads

  • failed: int count of failed downloads

  • details: list of dicts with download status per product

Return type:

Dict containing

Example

>>> searcher = CopernicusDataSearcher()
>>> searcher.query_by_filter(collection_name='SENTINEL-1', product_type='SLC', ...)
>>> df = searcher.execute_query()
>>> result = searcher.download_products(df=df, output_dir='./data')

Downloader Module

class phidown.downloader.TokenManager(username, password, token_url='https://identity.dataspace.copernicus.eu/auth/realms/cdse/protocol/openid-connect/token', client_id='cdse-public')[source]

Bases: object

Manages OAuth2 tokens with automatic refresh for Copernicus Data Space.

This class handles token lifecycle including automatic refresh before expiration to ensure uninterrupted access to CDSE APIs during burst downloads.

username[source]

CDSE account username.

password[source]

CDSE account password.

token_url[source]

OAuth2 token endpoint URL.

client_id[source]

OAuth2 client identifier.

access_token[source]

Current access token (None if not yet acquired).

expiry[source]

Token expiration time in epoch seconds.

Example

>>> token_mgr = TokenManager('user@example.com', 'password')
>>> token = token_mgr.get_access_token()
>>> # Token is automatically refreshed when expired
>>> token = token_mgr.get_access_token()
EXPIRY_BUFFER_SECONDS = 60[source]
__init__(username, password, token_url='https://identity.dataspace.copernicus.eu/auth/realms/cdse/protocol/openid-connect/token', client_id='cdse-public')[source]

Initialize TokenManager with credentials.

Parameters:

  • username (str) – CDSE account username.

  • password (str) – CDSE account password.

  • token_url (str) – OAuth2 token endpoint URL (default: CDSE token URL).

  • client_id (str) – OAuth2 client identifier (default: cdse-public).

get_access_token()[source]

Get current access token, refreshing if expired.

This method checks if the current token is valid and refreshes it if necessary before returning.

Returns:

Valid access token for API requests.

Return type:

str

Raises:

requests.exceptions.HTTPError – If token refresh fails.

refresh_access_token()[source]

Refresh the access token using password grant.

This method authenticates with CDSE using username/password credentials to obtain a fresh access token. The expiry is set with a buffer to ensure tokens are refreshed before actual expiration.

Raises:

requests.exceptions.HTTPError – If authentication request fails.

Return type:

None

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:

  • ValueError – 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, insecure_skip_verify=False)[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 – Either a TokenManager instance or a string access token.

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

Raises:

  • ValueError – If burst_id or token is empty.

  • RuntimeError – If burst processing fails or returns non-200 status.

Return type:

None

Example

>>> from pathlib import Path
>>> token_mgr = TokenManager('user@example.com', 'password')
>>> download_burst('12345678-1234-1234-1234-123456789abc', token_mgr, 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