sen2p

sen2p is a lightweight Python library to search, download, and manage Sentinel-2 imagery from Microsoft Planetary Computer. No API keys required.

Focused on data discovery + download + satellite utilities. For raster processing and analysis, use rasteric.

Installation

pip install sen2p

Requirements

• Python >= 3.9

Features

• 🔍 Search with cloud cover and date filtering
• 🏆 Auto-select best image (low cloud, good coverage, nearest date)
• 📍 Find nearest image to a specific date
• 🛰️ Download selected bands with friendly aliases (blue, nir, etc.)
• 📦 Auto-merge bands into single GeoTIFF
• ⚡ Parallel download (workers=N)
• 🔄 Retry with exponential backoff
• ♻️ Skip existing files
• 📊 Export metadata to CSV / footprints to GeoJSON
• 📅 Timeline visualization
• 🖥️ CLI: sen2p search, sen2p download, sen2p best, sen2p nearest, sen2p bandinfo, sen2p bands

Quick Start

Python

from sen2p import search, best_item, nearest, download, bandinfo, bands, timeline, preview, meta_df, export_meta

# Search
items = search("2023-06-01", "2023-06-30", [172.1, -43.5], cloud_max=20)
print(f"Found {len(items)} items")

# Timeline
timeline(items)

# Best image (lowest cloud, best coverage, nearest date)
item = best_item("2023-06-01", "2023-06-30", [172.1, -43.5])
preview(item)

# Nearest to a specific date
item = nearest("2023-06-15", [172.1, -43.5], cloud_max=20)

# Download with friendly band names
results = download(
    start_date="2023-06-01",
    end_date="2023-06-30",
    location=[172.1, -43.5],
    bands=["blue", "green", "red", "nir"],
    output_dir="output",
    cloud_max=20,
    workers=4,
)

# Export metadata
df = meta_df(items)
export_meta(items, "metadata.csv")

# Band info
info = bandinfo("nir")
# {'band': 'B08', 'name': 'NIR', 'resolution': '10m', 'wavelength': '842nm'}

CLI

# Search
sen2p search --start 2023-06-01 --end 2023-06-30 --location "172.1,-43.5" --cloud-max 20

# Best image
sen2p best --start 2023-06-01 --end 2023-06-30 --location "172.1,-43.5"

# Nearest to date
sen2p nearest --date 2023-06-15 --location "172.1,-43.5" --cloud-max 20

# Download with parallel workers
sen2p download --start 2023-06-01 --end 2023-06-10 --location "172.1,-43.5" \
    --bands blue,green,red,nir --output output --cloud-max 20 --workers 4

# Band info
sen2p bandinfo nir
sen2p bands

# Raster metadata
sen2p meta output/S2B_..._merged.tif

Location Formats

[172.1, -43.5]                              # Point [lon, lat]
[172.0, -43.6, 172.5, -43.3]               # Bounding box
"study_area.shp"                            # Shapefile path
"area.geojson"                              # GeoJSON file path
{"type": "Point", "coordinates": [172.1, -43.5]}  # GeoJSON dict

Band Aliases

Use friendly names instead of band codes:

from sen2p import bandinfo, bands

bandinfo("nir")  # {'band': 'B08', 'name': 'NIR', 'resolution': '10m', 'wavelength': '842nm'}
bands()          # Full dict of all bands

Functions

Search & Discovery

Download

Metadata

Visualization

Band Utilities

Integration with rasteric

from sen2p import download
from rasteric import ndvi, clip, plot

# Download
results = download(
    start_date="2023-06-01", end_date="2023-06-10",
    location=[172.1, -43.5], bands=["red", "nir"],
    output_dir="data", cloud_max=20,
)

# Process with rasteric
ndvi(results[0]["merged"], "ndvi.tif", red_band=1, nir_band=2)
clip("ndvi.tif", "boundary.shp", "ndvi_clipped.tif")
plot("ndvi_clipped.tif", bands=(1,), cmap="RdYlGn", title="NDVI")

Contributing

• Repository: github.com/tnmthai/sen2p
• Issues: github.com/tnmthai/sen2p/issues
• PyPI: pypi.org/project/sen2p

License

MIT License