sand.base
- class sand.base.BaseDownload[source]
Bases:
objectBase class for satellite data providers API access and download functionality.
This class provides a common interface for interacting with different satellite data providers. It handles authentication, querying products, downloading data and metadata retrieval. Child classes must implement the abstract methods for specific provider APIs.
- session
HTTP session for making API requests
- Type:
requests.Session
- ssl_ctx
SSL context for secure connections
- Type:
ssl.SSLContext
- available_collection
List of available collections from the provider
- Type:
list
- api_collection
Name of the collection in provider’s API format
- Type:
str
- name_contains
List of naming constraints for products
- Type:
list
- download(product: dict, dir: Path | str, if_exists: str = 'skip') Path[source]
Download a product from the API server.
- Parameters:
product (dict) – Product metadata obtained from query results
dir (Path|str) – Directory where to save the downloaded product
- Returns:
Path to the downloaded product file
- Return type:
Path
- download_all(products, dir: Path | str, if_exists: str = 'skip', parallelized: bool = False) list[Path][source]
Download all products from API server resulting from a query.
- Parameters:
products (list[dict]) – List of product metadata from query results
dir (Path|str) – Directory where to save downloaded products
if_exists (str, optional) – Action to take if product exists: - ‘skip’: Skip download if file exists (default) - ‘overwrite’: Replace existing file - ‘raise’: Raise an error if file exists
parallelized (bool, optional) – If True, downloads products in parallel using multiple threads. Default is False.
- Returns:
List of paths to downloaded product files
- Return type:
list[Path]
- download_file(product_id: str, dir: Path | str, api_collection: str = None) Path[source]
Download a specific product from API server by its product identifier
- Parameters:
product_id (str) – The identifier of the product to download (ex: S2A_MSIL1C_20190305T050701_N0207_R019_T44QLH_20190305T103028)
dir (Path | str) – Directory where to store the downloaded file
api_collection (str, optional) – Name of the API collection to query. If None, will determine from product_id pattern.
- Returns:
Path to the downloaded file
- Return type:
Path
- get_available_collection() dict[source]
Return every downloadable collections for selected provider
- metadata(product: dict) dict[source]
Retrieve detailed metadata for a product.
- Parameters:
product (dict) – Basic product metadata obtained from query results
- Returns:
- Detailed product metadata including:
attributes: Product attributes (e.g., cloud cover, quality flags)
assets: Available product assets (e.g., bands, ancillary data)
- Return type:
dict
- query(collection_sand: str = None, level: Literal[1, 2, 3] = 1, time: Time = None, geo: Geo = None, name: Name = None, cloudcover_thres: int = None, api_collection: list[str] = None) SandQuery[source]
Query products from the API server based on temporal and spatial constraints.
- Parameters:
collection_sand (str) – SAND collection name (‘SENTINEL-2-MSI’, ‘SENTINEL-3-OLCI’, etc.)
level (int) – Processing level (1, 2, or 3)
time (Time, optional) – Time constraint.
geo (Geo, optional) – Spatial constraint.
name (Name, optional) – Constraints over product name.
cloudcover_thres (int) – Upper bound for cloud cover in percentage,
api_collection (list[str]) – Name of deserved collection in API standard
- Returns:
Query results containing matching products
- Return type:
- quicklook(product: dict, dir: Path | str) Path[source]
Download a quicklook preview image for a product.
- Parameters:
product (dict) – Product metadata obtained from query results
dir (Path|str) – Directory where to save the quicklook image
- Returns:
Path to the downloaded quicklook image
- Return type:
Path
- sand.base.check_too_many_matches(response: dict, returned_tag: str | list[str], hit_tag: str | list[str]) None[source]
Check if an API query returned more matches than it can return in one response.
- Parameters:
response (dict) – API response containing result counts
returned_tag (str|list[str]) – Path to the number of returned results in response
hit_tag (str|list[str]) – Path to the total number of matches in response