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')[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”.
- Return type:
- 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, verbose=True)[source]
Download the EO product using the downloader module.
Downloader Module
- phidown.downloader.pull_down(s3path, outputdir, verbose=False)[source]
Pull down files from S3 using s5cmd with the specified command and configuration.