Metadata-Version: 2.4
Name: earthcare-downloader
Version: 1.11.0
Summary: Download EarthCARE satellite data
Project-URL: Homepage, https://github.com/actris-cloudnet/earthcare-downloader
Project-URL: Issues, https://github.com/actris-cloudnet/earthcare-downloader/issues
Author-email: Simo Tukiainen <simo.tukiainen@fmi.fi>
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.10
Requires-Dist: aiohttp
Requires-Dist: platformdirs
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: pre-commit; extra == 'dev'
Requires-Dist: release-version; extra == 'dev'
Requires-Dist: types-tqdm; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# <img src="logo.png" width="35px"> earthcare-downloader

[![CI](https://github.com/actris-cloudnet/earthcare-downloader/actions/workflows/test.yml/badge.svg)](https://github.com/actris-cloudnet/earthcare-downloader/actions/workflows/test.yml)
[![PyPI version](https://badge.fury.io/py/earthcare-downloader.svg)](https://badge.fury.io/py/earthcare-downloader)

A Python tool for searching and downloading [EarthCARE](https://earth.esa.int/eogateway/missions/earthcare) satellite data from the European Space Agency's (ESA) [MAAP catalog](https://catalog.maap.eo.esa.int/doc/stac.html).

## Installation

```bash
python3 -m pip install earthcare-downloader
```

## :penguin: CLI usage

### Authentication

Searching for data requires no authentication. Downloading requires a MAAP offline token:

1. Get a 90-day token from https://portal.maap.eo.esa.int/ini/services/auth/token/90dToken.php
2. Set it via one of these methods:
   - Environment variable: `export MAAP_TOKEN=your_token`
   - CLI flag: `--token your_token`
   - The program will prompt you on first use and cache the token at `~/.cache/earthcare_downloader/token`

### Running the program

```
earthcare-downloader -p PRODUCT [options]
```

where the arguments are:

| Argument                | Description                                                                     |
| ----------------------- | ------------------------------------------------------------------------------- |
| `-p`, `--product`       | Product type(s) to download (see full list below).                              |
| `--start`               | Start date (YYYY-MM-DD).                                                        |
| `--stop`                | Stop date (YYYY-MM-DD).                                                         |
| `-d`, `--date`          | Single date (YYYY-MM-DD). Overrides `--start` and `--stop`                      |
| `--orbit-min`           | Minimum orbit number.                                                           |
| `--orbit-max`           | Maximum orbit number.                                                           |
| `--orbit`               | Single orbit number. Overrides `--orbit-min` and `--orbit-max`                  |
| `--lat LAT`             | Latitude of the target location (-90..90 degrees). Use with `--lon` and `-r`    |
| `--lon LON`             | Longitude of the target location (-180..180 degrees). Use with `--lat` and `-r` |
| `-r`, `--radius`        | Search radius around the location in km. Use with `--lat` and `--lon`.          |
| `--lat-range LAT1,LAT2` | Latitude range (min_lat,max_lat) to search for data. Use with `--lon-range`.    |
| `--lon-range LON1,LON2` | Longitude range (min_lon,max_lon) to search for data. Use with `--lat-range`.   |
| `-o`, `--output-path`   | Directory to save downloaded files (default: current directory).                |
| `--by-product`          | Create subdirectories for each product type.                                    |
| `--max-workers`         | Maximum number of concurrent downloads (default: **5**).                        |
| `--token`               | MAAP offline token for authentication.                                          |
| `-q`, `--quiet`         | Hide progress bars during download.                                             |
| `-y`, `--yes`           | Skip confirmation prompt before downloading.                                    |
| `--all`                 | Download all versions of the file. By default download only the newest version. |
| `-f`, `--force`         | Force downloading, even if file with the same name exists in the target folder. |
| `-h`, `--help`          | Show help message and exit.                                                     |

Available products:

|                     **Level 1**                     | Product Code                                                                   | Description                                      |
| :-------------------------------------------------: | ------------------------------------------------------------------------------ | ------------------------------------------------ |
|                                                     | [ATL_NOM_1B](https://earthcarehandbook.earth.esa.int/catalogue/atl_nom_1b)     | ATLID Nominal Mode                               |
|                                                     | [AUX_JSG_1D](https://earthcarehandbook.earth.esa.int/catalogue/aux_jsg_1d)     | Auxiliary Joint Standard Grid                    |
|                                                     | [BBR_NOM_1B](https://earthcarehandbook.earth.esa.int/catalogue/bbr_nom_1b)     | Broadband Radiometer Nominal Mode                |
|                                                     | [BBR_SNG_1B](https://earthcarehandbook.earth.esa.int/catalogue/bbr_sng_1b)     | Broadband Radiometer Single View                 |
|                                                     | [CPR_NOM_1B](https://earthcarehandbook.earth.esa.int/catalogue/cpr_nom_1b)     | Cloud Profiling Radar Nominal Mode               |
|                                                     | [MSI_NOM_1B](https://earthcarehandbook.earth.esa.int/catalogue/msi_nom_1b)     | Multi-Spectral Imager Nominal Mode               |
|                                                     | [MSI_RGR_1C](https://earthcarehandbook.earth.esa.int/catalogue/msi_rgr_1c)     | Multi-Spectral Imager Re-Gridded                 |
|                    **Level 2A**                     |                                                                                |                                                  |
|                                                     | [ATL_AER_2A](https://earthcarehandbook.earth.esa.int/catalogue/atl_aer_2a)     | ATLID Aerosol Parameters                         |
|                                                     | [ATL_ALD_2A](https://earthcarehandbook.earth.esa.int/catalogue/atl_ald_2a)     | ATLID Aerosol Layer Descriptors                  |
|                                                     | [ATL_CLA_2A](https://earthcarehandbook.earth.esa.int/catalogue/atl_cla_2a)     | ATLID Cloud and Aerosol Classification           |
|                                                     | [ATL_CTH_2A](https://earthcarehandbook.earth.esa.int/catalogue/am__cth_2b)     | ATLID Cloud Top Height                           |
|                                                     | [ATL_EBD_2A](https://earthcarehandbook.earth.esa.int/catalogue/atl_ebd_2a)     | ATLID Extinction, Backscatter and Depolarization |
|                                                     | [ATL_FM\_\_2A](https://earthcarehandbook.earth.esa.int/catalogue/atl_fm__2a)   | ATLID Feature Mask                               |
|                                                     | [ATL_ICE_2A](https://earthcarehandbook.earth.esa.int/catalogue/atl_ice_2a)     | ATLID Ice Parameters                             |
|                                                     | [ATL_TC\_\_2A](https://earthcarehandbook.earth.esa.int/catalogue/ac__tc__2b)   | ATLID Target Classification                      |
|                                                     | [CPR_CD\_\_2A](https://earthcarehandbook.earth.esa.int/catalogue/cpr_cd__2a)   | CPR Cloud Doppler parameters                     |
|                                                     | [CPR_CLD_2A](https://earthcarehandbook.earth.esa.int/catalogue/cpr_cld_2a)     | CPR Cloud Parameters                             |
|                                                     | [CPR_FMR_2A](https://earthcarehandbook.earth.esa.int/catalogue/cpr_fmr_2a)     | CPR Feature Mask and Radar Reflectivity          |
|                                                     | [CPR_TC\_\_2A](https://earthcarehandbook.earth.esa.int/catalogue/cpr_tc__2a)   | CPR Target Classification                        |
|                                                     | [MSI_AOT_2A](https://earthcarehandbook.earth.esa.int/catalogue/msi_aot_2a)     | MSI Aerosol Optical Thickness                    |
|                                                     | [MSI_CM\_\_2A](https://earthcarehandbook.earth.esa.int/catalogue/msi_cm__2a)   | MSI Cloud Mask                                   |
|                                                     | [MSI_COP_2A](https://earthcarehandbook.earth.esa.int/catalogue/msi_cop_2a)     | MSI Cloud Optical Properties                     |
| <span title="JAXA product">:japanese_castle:</span> | [CPR_CLP_2A](https://eolp.jaxa.jp/EarthCARE_CPR_L2A_CPR_CLP.html)              | CPR Cloud Properties                             |
| <span title="JAXA product">:japanese_castle:</span> | [CPR_ECO_2A](https://eolp.jaxa.jp/EarthCARE_CPR_L2A_CPR_ECO.html)              | CPR Echo Characteristics                         |
| <span title="JAXA product">:japanese_castle:</span> | [MSI_CLP_2A](https://eolp.jaxa.jp/EarthCARE_MSI_L2A_MSI_CLP.html)              | MSI Cloud Properties                             |
|                    **Level 2B**                     |                                                                                |                                                  |
|                                                     | [ACM_CAP_2B](https://earthcarehandbook.earth.esa.int/catalogue/acm_cap_2b)     | ACM Closure Assessment Parameters                |
|                                                     | [ACM_COM_2B](https://earthcarehandbook.earth.esa.int/catalogue/acm_com_2b)     | ACM Composite Products                           |
|                                                     | [ACM_RT\_\_2B](https://earthcarehandbook.earth.esa.int/catalogue/acm_rt__2b)   | ACM Radiative Transfer                           |
|                                                     | [AC\_\_CLP_2B](https://earthcarehandbook.earth.esa.int/catalogue/ac__clp_2b)   | ATLID-CPR Synergy Cloud Properties               |
|                                                     | [AC\_\_TC\_\_2B](https://earthcarehandbook.earth.esa.int/catalogue/ac__tc__2b) | ATLID-CPR Target Classification                  |
|                                                     | [ALL_3D\_\_2B](https://earthcarehandbook.earth.esa.int/catalogue/all_3d__2b)   | Combined 3D Scene                                |
|                                                     | [ALL_DF\_\_2B](https://earthcarehandbook.earth.esa.int/catalogue/all_df__2b)   | Combined Broadband Radiative Fluxes              |
|                                                     | [AM\_\_ACD_2B](https://earthcarehandbook.earth.esa.int/catalogue/am__acd_2b)   | ATLID-MSI Aerosol Column Descriptors             |
|                                                     | [AM\_\_CTH_2B](https://earthcarehandbook.earth.esa.int/catalogue/am__cth_2b)   | ATLID-MSI Cloud Top Height                       |
|                                                     | [BMA_FLX_2B](https://earthcarehandbook.earth.esa.int/catalogue/bma_flx_2b)     | BBR-MSI-ATLID Radiative Fluxes                   |
|                                                     | [BM\_\_RAD_2B](https://earthcarehandbook.earth.esa.int/catalogue/bm__rad_2b)   | BBR-MSI Radiative Fluxes and Heating Rates       |
| <span title="JAXA product">:japanese_castle:</span> | [ACM_CLP_2B](https://eolp.jaxa.jp/EarthCARE_L2B_ACM_CLP.html)                  | ACM Cloud Properties                             |
| <span title="JAXA product">:japanese_castle:</span> | [ALL_RAD_2B](https://eolp.jaxa.jp/EarthCARE_L2B_ALL_RAD.html)                  | Combined Radiance                                |
|                   **Orbit Data**                    |                                                                                |                                                  |
|                                                     | [AUX_ORBPRE](https://earthcarehandbook.earth.esa.int/catalogue/aux_orbpre)     | Orbit Predictions                                |
|                                                     | [MPL_ORBSCT](https://earthcarehandbook.earth.esa.int/catalogue/mpl_orbsct)     | Orbit Scenario                                   |
|                    **MET Data**                     |                                                                                |                                                  |
|                                                     | [AUX_MET_1D](https://earthcarehandbook.earth.esa.int/catalogue/aux_met_1d)     | ECMWF meteorological parameters                  |
|                 **Auxiliary Data**                  |                                                                                |                                                  |
|                                                     | AUX_ORBRES                                                                     | Orbit Restitution                                |
|                                                     | BBR_SOL_1B                                                                     | BBR Solar Calibration                            |
|                                                     | GEO_ATTOBS                                                                     | Attitude Observations                            |
|                                                     | GEO_ORBOBS                                                                     | Orbit Observations                               |

<span title="JAXA product">:japanese_castle:</span> = [JAXA](https://www.eorc.jaxa.jp/EARTHCARE/) product

### Examples

Download all `CPR_TC__2A` overpass data within 5 km of Hyytiala, Finland:

```bash
earthcare-downloader -p CPR_TC__2A --lat 61.844 --lon 24.287 -r 5
```

Download all `ATL_ALD_2A` and `AUX_JSG_1D` data from two days:

```bash
earthcare-downloader -p ATL_ALD_2A,AUX_JSG_1D --start=2025-05-01 --stop=2025-05-02
```

## :snake: Python API

You can also use `earthcare-downloader` as a Python library:

```python
from earthcare_downloader import search, download

files = search(product="CPR_TC__2A", date="2025-01-01")
paths = download(files)
```

When working in notebooks, use the asynchronous versions of these functions:

```python
from earthcare_downloader.aio import search, download

files = await search(product="CPR_TC__2A", date="2025-01-01")
paths = await download(files)
```

## Disclaimer

This package provides tools to access data from the European Space Agency's (ESA)
MAAP catalog. The package does not host or redistribute ESA data.

All data are &copy; European Space Agency (ESA) and subject to the
[ESA Terms and Conditions](https://earth.esa.int/eogateway/terms-and-conditions).
Please ensure your use complies with ESA's non-commercial and attribution requirements.

## License

MIT
