enmap-downloader 0.6.5

Downloader for EnMAP data products with STAC

Downloader for EnMAP data products with STAC

• Free software: EUPL-1.2

• Documentation: https://global-land-monitoring.git-pages.gfz-potsdam.de/enmap_downloader/doc/

Status

See also the latest coverage report and the pytest HTML report.

Feature overview

The EnMAP Downloader is a Python-based tool designed to streamline access to hyperspectral imagery from the Earth Observation Center (EOC). It provides a flexible and efficient interface for searching, downloading, and preparing EnMAP data tailored to user-defined spatial and temporal criteria.

🌐 Download Hyperspectral EnMAP Data

• Fetches .tif hyperspectral datasets (EnMAP L2A) directly from the EOC archive.

🗺️ User-Defined Spatial Parameters

• Accepts a a single GeoJSON, or a folder of multiple GeoJSON files — each is handled automatically and clipped to the defined area.

🕒 User-Defined Temporal Filtering

• Specify a date range to download only the scenes captured within that timeframe.

⚡ Downloads in batches

• Optimizied for downloading in batches, reducing wait times and improving efficiency.

📂 Batch Processing of Multiple AOIs

• Efficiently processes multiple areas of interest in one go, especially useful for regional or project-wide data collection.

💾 Flexible Output Formats

• Outputs data as GeoTIFFs (.tif) or NumPy arrays (.npy)—choose based on your workflow.

🔐 Authentication & Config File Support

• Includes authentication checks and a customizable config file for repeatable, automated use.

✅ Typical Use Cases

• 🛰️ Collecting hyperspectral scenes for machine learning and remote sensing projects

• 🗃️ Handling a large folder of AOIs automatically for environmental or urban monitoring

• 🔄 Automating scheduled or repeatable data collection workflows

This Python package is primarily developed and tested on Linux OS. For Windows users, it is recommended to run the package via Windows Subsystem for Linux (WSL) to ensure full compatibility and proper functioning.

History / Changelog

You can find the protocol of recent changes in the EnMAP Downloader package here.

Credentials

To access the EnMAP data, you need to have a valid EOC account. You can register for an account at the EOC website, by visiting this link. Create your account and verify your email address, after that you need to add the permission to access the EnMAP data. You can do this by visiting this page and subscribing to the “EnMAP Access Service” permission as seen in the image below.

After that your account is properly set up and you can use the package.

When running the code for the first time, a .env file will be created in the root directory of the package. This file will contain the following variables:

ENMAP_USERNAME=USERNAME
ENMAP_PASSWORD=PASSWORD

You can edit this file to securely add your EOC credentials. The package will automatically read the credentials from this file when executing the code.

Important: This file contains sensitive information. To protect your credentials, keep it private and do not share it with others.

The package requires valid credentials to function properly. If the credentials are missing or incorrect, you will receive an error message.

Once saved, your credentials will be stored in the .netrc file in your home directory. This means you won’t need to enter them again for future runs.

Quick Installation

To install the package, clone it into a local directory and run the following command:

python -m pip install .

Alternatively you can create a conda environment and install the package with its dependencies:

conda env create -f environment_enmap_downloader.yml
conda activate enmap_downloader
pip install .

Make sure to create a config.json file in the config directory. You can use the provided example file as a template. The config.json file should contain the following information:

{
"search_settings": {
    "collections": [
    "ENMAP_HSI_L2A"
    ],
    "catalog_link" : "https://geoservice.dlr.de/eoc/ogc/stac/v1/",
    "aoi_settings": {
        "geojson": "./config/geojson",
        "start_date": "",
        "end_date": ""
    }
},
"result_settings": {
    "crop_value" : "bbox",
    "results_dir": "./downloads",
    "result_format": "tif",
    "logging_level": "INFO",
    "logging_dir": "./logs"
    "download_assets" : [
        "image",
        "metadata",
        "properties"
    ]
}

Configuration Options

Below is a description of the configurable parameters in the configuration file used by this project.

AOI Settings

These settings define the area of interest (AOI) and the time window for data selection.

"aoi_settings": {
    "geojson": "./config/geojson",
    "start_date": "",
    "end_date": ""
}

• geojson (str): Path to a GeoJSON file that defines the spatial parameters for the area of interest.

• start_date (str, optional): Start date for the data query, in YYYY-MM-DD format. Leave empty to ignore.

• end_date (str, optional): End date for the data query, in YYYY-MM-DD format. Leave empty to ignore.

Result Settings

These settings control how the results are processed, saved, and logged.

"result_settings": {
    "crop_value" : "bbox",
    "results_dir": "./downloads",
    "result_format": "tif",
    "logging_level": "INFO",
    "logging_dir": "./logs",
    "download_assets" : [
        "image",
        "metadata",
        "properties"
    ]
}

• crop_value (str):

  • If default, the data will not be cropped.

  • If bbox, the data will be cropped to the max bounds of the supplied geojson.

  • If precise, the data will be cropped to the exact polygon of the supplied geojson.

• results_dir (str): Directory path where result files will be saved.

• result_format (str): Format in which results are stored. Supported options: “npy” (NumPy array), “tif” (GeoTIFF).

• logging_level (str): Logging verbosity level. Typical values: “DEBUG”, “INFO”, “WARNING”, “ERROR”.

• logging_dir (str): Directory where log files are saved.

• download_assets (list of str):

  List of asset types to download. Supported options include “image”, “metadata”, and “properties”.

Then you can use the package by running the following code block:

import os

from enmap_downloader.config import loadConfiguration, Config
from enmap_downloader.enmap_downloader import enmapDownloader

if __name__ == "__main__":

    config_file = os.path.abspath("config/config.json")
    config = loadConfiguration(path=config_file)
    Config(**config)

    enmapDownloader(config)

The function enmapDownloader has the following parameters:

• config (Config): The configuration object containing all settings.

• limit (int, optional): Maximum number of items to download per query. If None, all items matching the query will be downloaded. Default is None.

The downloader will search for EnMAP data products based on the configuration provided, download the data, and save it in the specified format and directory. The downloaded files will be logged in the specified logging directory.

Jupyer Notebooks

To make it easier for new users, or anyone who wants to try out the package quickly, we provide a collection of Jupyter notebooks. These notebooks demonstrate a variety of common use cases and are designed to run out-of-the-box, with only the need for small adjustments. Each notebook contains step-by-step examples that can be executed interactively. This makes them well suited both for first explorations and for adapting the workflows to your own data or research questions. If you are new to the package, starting with the notebooks is the fastest way to get familiar with its core functionality.

FAQ

• Is there a possibility to just fetch the available data with given AOI and time range without downloading the data?

Yes, you can leave the “download_assets” list empty in the config.json file.

• When running the downloader, I am getting the error message “Error 403: Forbidden”. What can I do?

This error message indicates that your credentials are not correct or you do not have the permission to access the EnMAP data. Please make sure that you have a valid EOC account and that you have subscribed to the “EnMAP Access Service” permission as described in the Credentials section above. It may take some time until the permission is activated. The downloader reads the credentials from the .env file, which is located in your home directory. Please make sure that the credentials are correct and that the .env file is in the correct location. If all of this is correct, there might also be a problem with your username / password. The .netrc file only allows some special characters in the password. Try to especially avoid the following characters: and #.

Developed by

enmap_downloader has been developed by the Global Land Monitoring group and FERN.Lab at the GFZ Helmholtz Centre for Geosciences.

Copyright

Copyright (c) 2025 GFZ Helmholtz Centre for Geosciences.

Credits

This package was created with Cookiecutter and the fernlab/cookiecutter-py-package project template.