sand.usgs

class sand.usgs.DownloadUSGS[source]

Bases: BaseDownload

download(product: SandProduct, dir: Path | str, if_exists: Literal['skip', 'overwrite', 'backup', 'error'] = '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_file(product_id: str, dir: Path | str, api_collection: str | None = 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 with its extension (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

metadata(product)[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, level: Literal[1, 2, 3] = 1, time: Time | None = None, geo: Point | Polygon | Tile | None = None, name: Name | None = None, cloudcover_thres: int | None = None, api_collection: str | None = 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:

SandQuery

quicklook(product: SandProduct, 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