Setup

Installation

Set up a Python 3.11+ environment with pip available, then install the latest version from PyPI:

pip install earthcarekit

# Check installed version
ecdownload -V

# Update to the latest release whenever needed
pip install earthcarekit --upgrade

Advanced: Install Latest Pre-Release from GitHub.

pip install -U git+https://github.com/TROPOS-RSD/earthcarekit.git

# Or, install manually from a local clone
pip install .

Configuration

Set up a configuration file to define storage paths and access to data platforms. ESA products require an ESA account. Applied via Python, the settings are saved at ~/.config/earthcarekit/default_config.toml.

Before using the package, you need to set up a configuration file to define storage paths and download credentials. Downloading EarthCARE products requires an ESA account. You can create one at OADS or MAAP

Once applied via Python, your settings are saved to your home directory at ~/.config/earthcarekit/default_config.toml.

Warning

As of August 2025, data dissemination is transitioning from OADS to MAAP. OADS is still recommended for now, but will be phased out by the end of 2025.

Example: See an example configuration file.

example_config.toml

[local]
# Set a path to your root EarthCARE data directory,
# where local EarthCARE product files will be searched and downloaded to.
data_directory = ""

# Set a path to your root image directory,
# where saved plots will be put.
image_directory = ""

[download]
# You have 2 options to set your data access rights:
# 1. (recommended) Choose one: "commissioning", "calval" or "open", e.g.:
#         collections = "calval"
# 2. List individual collections, e.g.:
#         collections = [
#             "EarthCAREL1InstChecked",
#             "EarthCAREL2InstChecked",
#             ...
#         ]
collections = "open"

# Set your data dissemination service that will be used for remote data search and download.
# Choose one: "oads" or "maap"
platform = "oads"

# If you've choosen "maap", generate a data access token on EarthCARE MAAP and put it here:
# (see <https://portal.maap.eo.esa.int/earthcare/>)
maap_token = ""

# If you've choosen "oads", give your OADS credencials here:
# (see <https://ec-pdgs-dissemination1.eo.esa.int> and <https://ec-pdgs-dissemination2.eo.esa.int>)
oads_username = "my_username"
oads_password = """my_password"""

Configuration via the Python Interpreter

Open the Python interpreter and generate an example configuration file in your current directory:
```
$ python
>>> import earthcarekit as eck
>>> eck.create_example_config()
```
Edit the generated file.

Follow the instructions in the inline comments of the exsample file to customize your settings. You may rename and save your file to any location.
Go back to the Python Interpreter and apply your configuration file as default:
```
>>> eck.set_config(path_to_file)
>>> exit()
```

You can later view or manually edit the saved configuration at ~/.config/earthcarekit/default_config.toml. To update your settings, you can also simply repeat the steps above.