Smart Sentinel Downloader

A high-performance Python SDK and CLI tool for discovering, streaming, and selectively downloading Sentinel-1 and Sentinel-2 satellite imagery from the Copernicus Data Space Ecosystem (CDSE).

Release v1.0.0 Python 3.8 – 3.14 MIT License Astral uv Powered

Terminal

# Install globally and download True Color bands directly
pip install smart-sentinel-downloader
sentinel-dl search --bbox 12.3 41.7 12.7 42.1 --start 2024-05-01 --download --bands rgb

Overview

Following the retirement of ESA's legacy SciHub (Copernicus Open Access Hub), the global remote sensing and Earth Observation (EO) community migrated to the Copernicus Data Space Ecosystem (CDSE). Standard portals force users to download entire multi-gigabyte .SAFE ZIP archives just to inspect a single 10m visible band or SAR polarization.

Smart Sentinel Downloader solves this by allowing selective asset extraction directly over HTTP with cryptographic validation, automatic download resumption, STAC catalog queries, and automated GeoTIFF composite generation.

Key Capabilities

⚡ 90% Bandwidth Savings

Download only target bands (TCI, RGB, NIR, NDVI) rather than the complete 1.1 GB SAFE package.

🔍 Built-in STAC Search

Search by bounding box, date range, and maximum cloud cover percentage without opening a browser.

🔄 Resumable HTTP Transfers

Automatic byte-range (Range: bytes=...) resumption so dropped connections never start over from 0%.

🛡️ Cryptographic Integrity

Automated MD5 and SHA256 checksum verification against CDSE metadata before file staging.

🗺️ QGIS & ArcGIS Export

Export search footprints straight to GeoJSON or CSV with one click.

🎨 Auto GeoTIFF Composites

Automatically merge single-band JP2 rasters into 3-band True Color or False Color GeoTIFFs.

Installation Guide

Smart Sentinel Downloader is available as a global CLI command (sentinel-dl / smart-sentinel) and an importable Python library.

1. Global CLI Install (Recommended)

Install via pip or Astral uv tool for isolated, instant terminal access from any directory:

Terminal

# Standard install via pip
pip install smart-sentinel-downloader

# With optional geospatial extras (rasterio for JP2 -> COG & Composites)
pip install "smart-sentinel-downloader[geo]"

# Or via Astral uv tool (isolated global CLI)
uv tool install smart-sentinel-downloader

2. From Source

Bash

git clone https://github.com/lokeshsk/Smart-Sentinel-Data-Downloader.git
cd Smart-Sentinel-Data-Downloader
uv venv
uv pip install -e ".[dev]"

Authentication

Create a .env file in your project or root directory:

.env

SENTINEL_USER=your_email@example.com
SENTINEL_PASS=your_secret_password

Verify connectivity and credentials directly in your terminal:

Terminal

sentinel-dl auth

CLI Command Reference

1. Catalog Search (`sentinel-dl search`)

Query CDSE STAC and OData catalog using spatial bounding boxes, dates, and cloud thresholds:

Terminal

# Search Sentinel-2 scenes over Rome with <15% cloud cover
sentinel-dl search \
  --bbox 12.3 41.7 12.7 42.1 \
  --start 2024-05-01 \
  --end 2024-05-31 \
  --max-cloud 15 \
  --limit 5

# Direct Search & Download
sentinel-dl search --bbox 77.1 28.5 77.3 28.7 --start 2024-06-01 --download --bands rgb

2. GeoJSON & CSV Search Export (`--export`)

Export footprints for instant viewing in QGIS, ArcGIS, or tabular analysis:

Terminal

# Export footprints to GeoJSON
sentinel-dl search --bbox 12.3 41.7 12.7 42.1 --start 2024-05-01 --export footprints.geojson

# Export tabular metadata to CSV
sentinel-dl search --bbox 77.1 28.5 77.3 28.7 --start 2024-06-01 --export summary.csv

3. Product Download (`sentinel-dl download`)

Download full product ZIPs or selective bands using product UUIDs or SAFE names:

Terminal

# Selective download: True Color & 10m RGB bands
sentinel-dl download b44fc1ca-4852-488f-a492-929a2e483c4a --bands rgb

# Selective download: Red (B04) and NIR (B08) for NDVI
sentinel-dl download S2B_MSIL2A_20240113T062129_... --bands ndvi

# Full complete ZIP download with resume support
sentinel-dl download b44fc1ca-4852-488f-a492-929a2e483c4a --type full

# Batch download from text file with 8 worker threads
sentinel-dl download --file sample_ids.txt --workers 8 --output-dir ./data

4. Automated GeoTIFF Composites (`--composite`)

Automatically merges constituent bands into a georeferenced 3-band GeoTIFF:

Terminal

# Natural True Color RGB Composite (B04, B03, B02)
sentinel-dl download b44fc1ca-4852-488f-a492-929a2e483c4a --composite rgb

# False Color Infrared Composite (B08 NIR, B04 Red, B03 Green)
sentinel-dl download b44fc1ca-4852-488f-a492-929a2e483c4a --composite false-color

5. Product Inspection (`sentinel-dl info`)

Inspect internal file assets, resolutions, and sizes before downloading:

Terminal

sentinel-dl info b44fc1ca-4852-488f-a492-929a2e483c4a

Band Presets Reference

Mission	Preset	Bands Included	Description
Sentinel-2	`rgb`	TCI, B04, B03, B02	Natural visual True Color + 10m visible channels
Sentinel-2	`tci`	TCI	True Color Image (single 10m visual asset)
Sentinel-2	`vnir`	B02, B03, B04, B08	10m Visible & Near-Infrared
Sentinel-2	`ndvi`	B04, B08	Red + NIR for vegetation index calculation
Sentinel-2	`ndwi`	B03, B08	Green + NIR for water delineation
Sentinel-2	`swir`	B11, B12, B8A	Short-wave infrared for moisture & fire scars
Sentinel-2	`scl`	SCL	20m Scene Classification Layer (cloud mask)
Sentinel-2	`all`	All 13 spectral bands + TCI + SCL	Complete multi-spectral asset suite
Sentinel-1	`vh`	VH	Cross-polarization SAR TIFF
Sentinel-1	`vv`	VV	Co-polarization SAR TIFF
Sentinel-1	`dual`	VH, VV	Dual polarization SAR pair

Python SDK Usage

Integrate directly into Jupyter Notebooks, automated data pipelines, or machine learning workflows:

Python

from smart_sentinel import CDSEClient, Downloader, export_search_results

# 1. Initialize client
client = CDSEClient()

# 2. Search catalog
scenes = client.search(
    collection="SENTINEL-2",
    bbox=[12.3, 41.7, 12.7, 42.1],
    start_date="2024-05-01",
    end_date="2024-05-15",
    max_cloud_cover=10.0,
    limit=5
)

# 3. Export footprints to GeoJSON
export_search_results(scenes, "search_footprints.geojson")

# 4. Download selective bands with automated RGB composite
downloader = Downloader(client=client, download_dir="./downloads")
results = downloader.download_selective_bands(scenes[0].id, composite="rgb")

for r in results:
    print(f"Downloaded: {r.filename} -> {r.output_path}")

Geospatial Post-Processing API

Python

from pathlib import Path
from smart_sentinel.processors import convert_jp2_to_geotiff, calculate_ndvi

# Convert Sentinel-2 JPEG2000 into standard GeoTIFF
geotiff = convert_jp2_to_geotiff(Path("downloads/T41RMH_B04_10m.jp2"))

# Compute NDVI raster
ndvi = calculate_ndvi(
    b04_path=Path("downloads/T41RMH_B04_10m.jp2"),
    b08_path=Path("downloads/T41RMH_B08_10m.jp2"),
    output_path=Path("downloads/ndvi.tif")
)

Benchmarks: Bandwidth Savings

Download Target	Legacy Full Product ZIP	Smart Selective Downloader	Savings
True Color (TCI 10m)	1,120 MB	115 MB	89.7% Saved
NDVI Bands (B04 + B08)	1,120 MB	220 MB	80.3% Saved
Sentinel-1 VH Polarization	850 MB	140 MB	83.5% Saved

Smart Sentinel Downloader

Overview

Key Capabilities

⚡ 90% Bandwidth Savings

🔍 Built-in STAC Search

🔄 Resumable HTTP Transfers

🛡️ Cryptographic Integrity

🗺️ QGIS & ArcGIS Export

🎨 Auto GeoTIFF Composites

Installation Guide

1. Global CLI Install (Recommended)

2. From Source

Authentication

CLI Command Reference

1. Catalog Search (sentinel-dl search)

2. GeoJSON & CSV Search Export (--export)

3. Product Download (sentinel-dl download)

4. Automated GeoTIFF Composites (--composite)

5. Product Inspection (sentinel-dl info)

Band Presets Reference

Python SDK Usage

Geospatial Post-Processing API

Benchmarks: Bandwidth Savings

1. Catalog Search (`sentinel-dl search`)

2. GeoJSON & CSV Search Export (`--export`)

3. Product Download (`sentinel-dl download`)

4. Automated GeoTIFF Composites (`--composite`)

5. Product Inspection (`sentinel-dl info`)