Copernicus Data Space Ecosystem (CDSE)¶

The cdse gatherer queries the Copernicus Data Space Ecosystem OData and STAC catalogues to search and download Earth observation data from the Sentinel constellation.

Overview¶

Provider: European Space Agency (ESA) / European Commission
Official Web Portal: dataspace.copernicus.eu
Documentation & APIs: documentation.dataspace.copernicus.eu
Registration: CDSE Account Registration (free account)
Missions: Sentinel-1 (SAR), Sentinel-2 (MSI), Sentinel-3 (OLCI/SLSTR), Sentinel-5P (TROPOMI), Sentinel-6
Capabilities: Full archive, Near Real Time (NRT), Non Time Critical (NTC), direct S3 path resolution
Authentication: Requires CDSE account (email and password)
Output Format: SAFE archives, NetCDF-4, or direct s3://eodata/ URIs

Supported Instruments & Products¶

Instrument	Product Types	Description
MSI (Sentinel-2)	`S2MSI2A`, `S2MSI1C`	Multi-Spectral Imager Surface Reflectance (BOA) / Top of Atmosphere (TOA)
OLCI (Sentinel-3)	`OL_1_EFR___`, `OL_2_WFR___`, `OL_2_LFR___`	Ocean and Land Colour Instrument TOA & water/land products
SLSTR (Sentinel-3)	`SL_1_RBT___`, `SL_2_LST___`, `SL_2_FRP___`	Sea and Land Surface Temperature Radiometer
TROPOMI (Sentinel-5P)	`AER_LH`, `AER_AI`, `NO2____`, `O3_____`, `SO2____`, `CH4____`, `CO_____`, `HCHO___`	TROPOspheric Monitoring Instrument trace gases and aerosol properties
SAR (Sentinel-1)	`SLC`, `GRD`	Synthetic Aperture Radar imaging

Parameters Reference¶

Parameter	Type	Default	Description
`instrument`	`str`	required	Instrument identifier (`"MSI"`, `"OLCI"`, `"SLSTR"`, `"TROPOMI"`, `"SAR"`)
`product_type`	`str \\| None`	`None`	Product type code (e.g. `"S2MSI2A"`, `"OL_1_EFR___"`, `"AER_LH"`)
`start_time`	`str`	required	Start datetime in ISO 8601 (e.g. `"2024-07-01T00:00:00Z"`)
`end_time`	`str`	required	End datetime in ISO 8601 (e.g. `"2024-07-05T23:59:59Z"`)
`timeliness`	`str \\| None`	`None`	Processing timeliness: `"NTC"` (Non-Time-Critical / Offline), `"NRT"` (Near-Real-Time), `"STC"`
`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]`
`max_cloud_cover`	`float \\| None`	`None`	Maximum allowable cloud cover percentage (e.g. `20.0`)
`limit`	`int \\| None`	`None`	Maximum number of products to download/return
`max_workers`	`int`	`1`	Number of concurrent worker threads for downloading multiple products
`only_granules_list`	`bool`	`False`	Return matching product URLs/names without downloading

Authentication Setup¶

Create a free account on the Copernicus Data Space Ecosystem Registration Page. After verifying your email, configure your credentials:

# Save to credentials.yaml
gathering auth login cdse -u "your_email@domain.com" -p "your_password"

# Or set in environment
export CDSE_USERNAME="your_email@domain.com"
export CDSE_PASSWORD="your_password"

Python API Usage¶

from gathering import Task

# Task 1: Sentinel-2 MSI Level 2A over Granada with cloud filter
task_s2 = Task.cdse(
    instrument="MSI",
    product_type="S2MSI2A",
    start_time="2024-07-01T00:00:00Z",
    end_time="2024-07-05T23:59:59Z",
    grid={"site": "Granada", "size_yx": [100, 100], "resolution_m": 1000.0},
    max_cloud_cover=20.0,
    limit=3,
)

# Task 2: Sentinel-5P TROPOMI NO2 Offline
task_s5p = Task.cdse(
    instrument="TROPOMI",
    product_type="NO2____",
    timeliness="NTC",
    start_time="2024-06-15T00:00:00Z",
    end_time="2024-06-15T04:00:00Z",
    grid={"site": "El_Arenosillo", "size_yx": [100, 100], "resolution_m": 1000.0},
    limit=2,
)

CLI Usage¶

gathering cdse \
  --instrument MSI \
  --product_type S2MSI2A \
  --start_time 2024-07-01T00:00:00Z \
  --end_time 2024-07-05T23:59:59Z

YAML Configuration¶

Sentinel-2 MSISentinel-3 OLCI & SLSTRSentinel-5P TROPOMI

# ==============================================================================
# Copernicus Data Space Ecosystem (CDSE) — Sentinel-2 MSI
# ==============================================================================

source: cdse

# --- Authentication (Optional inline; alternatively use CDSE_USERNAME/PASSWORD) ---
# username: "your_email@domain.com"
# password: "your_cdse_password"

instrument: MSI
product_type: S2MSI2A                  # Level-2A BOA reflectance

start_time: "2024-07-01T00:00:00Z"
end_time: "2024-07-05T23:59:59Z"

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

max_cloud_cover: 20.0                  # Filter granules with <= 20% cloud cover
limit: 3
only_granules_list: false
return_s3_paths: false

# ==============================================================================
# Copernicus Data Space Ecosystem (CDSE) — Sentinel-3 OLCI & SLSTR
# ==============================================================================

logging:
  level: INFO

tasks:
  # Task 1: Sentinel-3 OLCI Top of Atmosphere Full Resolution
  - source: cdse
    instrument: OLCI
    product_type: OL_1_EFR___
    timeliness: NTC                      # Non-Time Critical (Offline)
    start_time: "2024-07-01T10:00:00Z"
    end_time: "2024-07-01T12:00:00Z"
    grid:
      site: "Granada"                    # AERONET station
      size_yx: [100, 100]
      resolution_m: 1000.0
      projection: "latlon"
    limit: 2

  # Task 2: Sentinel-3 SLSTR Land Surface Temperature (NRT)
  - source: cdse
    instrument: SLSTR
    product_type: SL_2_LST___
    timeliness: NRT                      # Near Real Time
    start_time: "2024-07-01T10:00:00Z"
    end_time: "2024-07-01T12:00:00Z"
    grid:
      site: "El_Arenosillo"
      size_yx: [100, 100]
      resolution_m: 1000.0
      projection: "latlon"
    limit: 2

# ==============================================================================
# Copernicus Data Space Ecosystem (CDSE) — Sentinel-5P TROPOMI
# ==============================================================================

source: cdse

instrument: TROPOMI
product_type: AER_LH                   # Aerosol Layer Height

timeliness: OFFL                       # Offline / NTC

start_time: "2024-06-15T00:00:00Z"
end_time: "2024-06-15T04:00:00Z"

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

limit: 5
overwrite_cache: false

Download Directory Structure¶

/workspace/.cache/gathering/cdse/
└── MSI/
    └── S2MSI2A/
        └── 2024/
            └── 07/
                └── 01/
                    └── S2A_MSIL2A_20240701T105621_N0510_R094_T30SVG_20240701T143612.SAFE.zip