earthcare-downloader 1.11.0

Download EarthCARE satellite data

earthcare-downloader

A Python tool for searching and downloading EarthCARE satellite data from the European Space Agency's (ESA) MAAP catalog.

Installation

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	ATLID Nominal Mode
	AUX_JSG_1D	Auxiliary Joint Standard Grid
	BBR_NOM_1B	Broadband Radiometer Nominal Mode
	BBR_SNG_1B	Broadband Radiometer Single View
	CPR_NOM_1B	Cloud Profiling Radar Nominal Mode
	MSI_NOM_1B	Multi-Spectral Imager Nominal Mode
	MSI_RGR_1C	Multi-Spectral Imager Re-Gridded
Level 2A
	ATL_AER_2A	ATLID Aerosol Parameters
	ATL_ALD_2A	ATLID Aerosol Layer Descriptors
	ATL_CLA_2A	ATLID Cloud and Aerosol Classification
	ATL_CTH_2A	ATLID Cloud Top Height
	ATL_EBD_2A	ATLID Extinction, Backscatter and Depolarization
	ATL_FM__2A	ATLID Feature Mask
	ATL_ICE_2A	ATLID Ice Parameters
	ATL_TC__2A	ATLID Target Classification
	CPR_CD__2A	CPR Cloud Doppler parameters
	CPR_CLD_2A	CPR Cloud Parameters
	CPR_FMR_2A	CPR Feature Mask and Radar Reflectivity
	CPR_TC__2A	CPR Target Classification
	MSI_AOT_2A	MSI Aerosol Optical Thickness
	MSI_CM__2A	MSI Cloud Mask
	MSI_COP_2A	MSI Cloud Optical Properties
:japanese_castle:	CPR_CLP_2A	CPR Cloud Properties
:japanese_castle:	CPR_ECO_2A	CPR Echo Characteristics
:japanese_castle:	MSI_CLP_2A	MSI Cloud Properties
Level 2B
	ACM_CAP_2B	ACM Closure Assessment Parameters
	ACM_COM_2B	ACM Composite Products
	ACM_RT__2B	ACM Radiative Transfer
	AC__CLP_2B	ATLID-CPR Synergy Cloud Properties
	AC__TC__2B	ATLID-CPR Target Classification
	ALL_3D__2B	Combined 3D Scene
	ALL_DF__2B	Combined Broadband Radiative Fluxes
	AM__ACD_2B	ATLID-MSI Aerosol Column Descriptors
	AM__CTH_2B	ATLID-MSI Cloud Top Height
	BMA_FLX_2B	BBR-MSI-ATLID Radiative Fluxes
	BM__RAD_2B	BBR-MSI Radiative Fluxes and Heating Rates
:japanese_castle:	ACM_CLP_2B	ACM Cloud Properties
:japanese_castle:	ALL_RAD_2B	Combined Radiance
Orbit Data
	AUX_ORBPRE	Orbit Predictions
	MPL_ORBSCT	Orbit Scenario
MET Data
	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

:japanese_castle: = JAXA product

Examples

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

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:

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:

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:

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 © European Space Agency (ESA) and subject to the ESA Terms and Conditions. Please ensure your use complies with ESA's non-commercial and attribution requirements.

License

MIT