ESA EarthCARE¶

The earthcare gatherer queries the ESA Multi-Mission Algorithm and Analysis Platform (MAAP) STAC API and OADS endpoint to search and download observations from the Earth Cloud Aerosol and Radiation Explorer (EarthCARE) satellite.

Overview¶

Provider: European Space Agency (ESA) / JAXA / MAAP
Official Mission Website: earthcare.esa.int
ESA MAAP Data Portal: maap.eo.esa.int
Registration / IAM Account: ESA MAAP Identity Management
Data Access & Token Guide: ESA EO Gateway EarthCARE Data
Mission: EarthCARE (launched May 2024)
Instruments:
ATLID: Atmospheric Lidar (355 nm high-spectral-resolution lidar)
CPR: Cloud Profiling Radar (94 GHz Doppler radar)
MSI: Multi-Spectral Imager (visible, near-infrared, shortwave, thermal)
BBR: Broad-Band Radiometer
Joint Synergy: Joint ATLID + CPR + MSI retrieved microphysical products
Authentication: ESA MAAP username/password or bearer token
Output Format: HDF5 / NetCDF-4 binary format

Supported Collections & Product Types¶

Collection ID	Instrument	Product Types	Description
`EARTHCARE_ATLID_L1B`	ATLID	`ATL_NOM_1B`	Nominal calibrated attenuated backscatter profiles
`EARTHCARE_ATLID_L2A`	ATLID	`ATL_AER_2A`, `ATL_TC__2A`, `ATL_EBD_2A`	Aerosol extinction/backscatter profiles, target classification
`EARTHCARE_CPR_L1B`	CPR	`CPR_NOM_1B`	Calibrated radar reflectivity factor
`EARTHCARE_CPR_L2A`	CPR	`CPR_CLD_2A`, `CPR_TC__2A`	Cloud mask, microphysics, target classification
`EARTHCARE_MSI_L1C`	MSI	`MSI_RGR_1C`	Top-of-atmosphere radiance and reflectance
`EARTHCARE_AC_L2A`	Synergy	`AC__TC__2A`, `AC__CLD_2A`	Joint ATLID + CPR synergy profiles
`EARTHCARE_ACM_L2A`	Synergy	`ACM_CAP_2A`, `ACM_RT__2A`	Joint ATLID + CPR + MSI cloud and aerosol properties

Parameters Reference¶

Parameter	Type	Default	Description
`collections`	`list[str]`	required	ESA MAAP collection IDs
`product_types`	`list[str]`	required	Product type codes
`start_time`	`str`	required	Start datetime in ISO 8601 (e.g. `"2024-09-01T00:00:00Z"`)
`end_time`	`str`	required	End datetime in ISO 8601 (e.g. `"2024-09-02T23:59:59Z"`)
`grid`	`Grid \\| dict \\| None`	`None`	Spatial Region of Interest (ROI) with center or `site`
`bounding_box`	`list[float] \\| None`	`None`	`[min_lon, min_lat, max_lon, max_lat]`
`limit`	`int \\| None`	`None`	Maximum number of products to download
`max_workers`	`int`	`1`	Number of concurrent worker threads for downloading multiple granules
`is_download`	`bool`	`True`	Set to `False` to list matching granules without downloading

Authentication Setup¶

Create a user account on ESA MAAP Identity Management.
Request EarthCARE data access via the ESA EO Gateway.
Alternatively, obtain your offline Bearer Token from ESA MAAP Account Management.
Configure your credentials:

# Save to credentials.yaml
gathering auth login earthcare -u "your_username" -p "your_password"

# Or set in environment
export EARTHCARE_USERNAME="your_username"
export EARTHCARE_PASSWORD="your_password"

Python API Usage¶

from gathering import Task

# Task 1: ATLID Level 1B & 2A profiles over Granada
task_atlid = Task.earthcare(
    collections=["EARTHCARE_ATLID_L1B", "EARTHCARE_ATLID_L2A"],
    product_types=["ATL_NOM_1B", "ATL_AER_2A", "ATL_TC__2A"],
    start_time="2024-09-01T00:00:00Z",
    end_time="2024-09-02T23:59:59Z",
    grid={"site": "Granada", "size_yx": [100, 100], "resolution_m": 1000.0},
)

# Task 2: CPR Cloud Radar & ATLID-CPR Synergy
task_cpr = Task.earthcare(
    collections=["EARTHCARE_CPR_L1B", "EARTHCARE_AC_L2A"],
    product_types=["CPR_NOM_1B", "AC__TC__2A"],
    start_time="2024-09-01T00:00:00Z",
    end_time="2024-09-02T23:59:59Z",
    bounding_box=[-10.0, 35.0, 5.0, 45.0],
    limit=5,
)

CLI Usage¶

gathering earthcare \
  --collections EARTHCARE_ATLID_L1B \
  --product_types ATL_NOM_1B \
  --start_time 2024-09-01T00:00:00Z \
  --end_time 2024-09-02T23:59:59Z

YAML Configuration¶

ATLID Lidar ProfilesCPR Radar & SynergyMSI Multi-Spectral Imager

# ==============================================================================
# ESA EarthCARE — Atmospheric Lidar (ATLID)
# ==============================================================================

source: earthcare

collections:
  - "EARTHCARE_ATLID_L1B"
  - "EARTHCARE_ATLID_L2A"

product_types:
  - "ATL_NOM_1B"
  - "ATL_AER_2A"
  - "ATL_TC__2A"

start_time: "2024-09-01T00:00:00Z"
end_time: "2024-09-02T23:59:59Z"

grid:
  center_lat_lon: [37.164, -3.605]   # Granada, Spain
  size_yx: [100, 100]
  resolution_m: 1000.0
  projection: "latlon"

overwrite_cache: false

# ==============================================================================
# ESA EarthCARE — Cloud Profiling Radar (CPR) & Multi-Instrument Synergy
# ==============================================================================

source: earthcare

collections:
  - "EARTHCARE_CPR_L1B"
  - "EARTHCARE_CPR_L2A"
  - "EARTHCARE_AC_L2A"                 # Joint ATLID + CPR synergy

product_types:
  - "CPR_NOM_1B"                       # CPR Level 1B calibrated reflectivity
  - "CPR_CLD_2A"                       # CPR Level 2A cloud mask & microphysics
  - "AC__TC__2A"                       # Synergy Target Classification

start_time: "2024-09-01T00:00:00Z"
end_time: "2024-09-02T23:59:59Z"

bounding_box: [-10.0, 35.0, 5.0, 45.0]

limit: 5
overwrite_cache: false

# ==============================================================================
# ESA EarthCARE — Multi-Spectral Imager (MSI)
# ==============================================================================

source: earthcare

collections:
  - EARTHCARE_MSI_L1C

product_types:
  - MSI_RGR_1C                         # Top-of-Atmosphere Radiance & Reflectance

start_time: "2025-04-08T00:00:00Z"
end_time: "2025-04-08T23:59:59Z"

grid:
  site: "Granada"
  size_yx: [100, 100]
  resolution_m: 1000.0
  projection: "latlon"

is_download: true
overwrite_cache: false

Download Directory Structure¶

/workspace/.cache/gathering/earthcare/
└── EARTHCARE_ATLID_L1B/
    └── ATL_NOM_1B/
        └── 2024/
            └── 09/
                └── 01/
                    └── ECA_EXPA_ATL_NOM_1B_20240901T103214_...h5