Current release info

Name	Downloads	Version	Platforms

earthlens — a unified Python client for satellite & climate data

earthlens gives you one consistent Python API for downloading satellite and climate data from four very different providers — UCSB CHIRPS, ERA5 on AWS, the ECMWF Climate Data Store, and Google Earth Engine — and turning the results into analysis-ready GeoTIFFs.

It is part of the serapeum-org open-source ecosystem and is built on top of pyramids-gis for raster I/O.

Why earthlens?

Each provider speaks its own dialect: CHIRPS is anonymous FTP with date-coded filenames, ERA5-on-S3 is unsigned object storage with a per-month layout, the ECMWF CDS expects a JSON request body validated against a constraints graph, and Google Earth Engine is a server-side image-collection model. earthlens flattens that into one call:

from earthlens.core import EarthLens

earthlens = EarthLens(
    data_source="ecmwf",          # or "chc" (alias "chirps"), "amazon-s3", "gee"
    temporal_resolution="monthly",
    start="2022-01-01",
    end="2022-12-01",
    variables={
        "reanalysis-era5-single-levels-monthly-means": [
            "2m-temperature",
            "total-precipitation",
        ],
    },
    lat_lim=[37.0, 38.0],
    lon_lim=[23.0, 24.0],
    path="data/era5",
)
earthlens.download()

You get back per-date, per-variable GeoTIFFs in data/era5/ — clipped to your bbox, ready to feed into a hydrology model, a PV-yield notebook, a heat-wave study, or anything else downstream.

Features

• Four backends, one facade. EarthLens(data_source=...) routes to CHIRPS, ERA5-on-S3, ECMWF/CDS, or Google Earth Engine without changing the rest of your code.
• YAML variable catalogs for ECMWF and GEE — every variable carries metadata: NetCDF name, units, accumulation semantics (is_flux), allowed pressure levels, monthly counterparts. Browseable with Catalog().get_variable(...).
• Pre-flight request validation against the live CDS constraints.json graph. Bad date / area / variable combinations are rejected before bytes go over the wire, with actionable error messages.
• Temporal aggregation built in. Pass an AggregationConfig to download() and earthlens emits aggregated GeoTIFFs alongside the raw NetCDFs. op="auto" reduces state variables (temperature, SST, soil moisture) by mean and flux variables (precipitation, radiation, evaporation) by sum — the physically correct choice driven by catalog metadata.
• Pressure-level support. ERA5 pressure-level fields (4-D NetCDFs) can be sliced to a specific level on download.
• Bbox cropping & NetCDF→GeoTIFF conversion are handled by pyramids-gis under the hood.
• Modular install extras — only install the SDK for the backend you need (pip install earthlens[ecmwf], [s3], [gee]).
• Strictly typed. Pydantic v2 models for catalog rows and request specs; modern PEP 585/604 type hints; Python 3.11 / 3.12 tested in CI.

Supported data sources

earthlens wraps 48 providers behind the one EarthLens(data_source=..., ...) facade — pass the data_source value below and everything else (auth, request shaping, output format) is handled per-backend. See Data Sources for the full walkthrough of each one.

Air quality

	Provider	data_source
	AirNow (US EPA)	airnow
	European Environment Agency	eea-aq
	OpenAQ	openaq
	Sensor.Community	sensor-community

Biodiversity & protected areas

	Provider	data_source
	GBIF	gbif
	IUCN Red List	iucn
	OBIS	obis
	Protected Planet (UNEP-WCMC)	wdpa

Climate reanalysis & projections

	Provider	data_source
	Copernicus Climate Data Store (ECMWF)	ecmwf
	NOAA Physical Sciences Laboratory	climate-indices
	WCRP CMIP6	cmip6

Disasters & risk

	Provider	data_source
	FDSN	fdsn
	GDACS	gdacs
	NASA FIRMS	firms
	ThinkHazard! (GFDRR/World Bank)	thinkhazard

Elevation & bathymetry

	Provider	data_source
	Copernicus DEM (ESA)	dem
	GEBCO	bathymetry

Glaciers & cryosphere

	Provider	data_source
	NSIDC Randolph Glacier Inventory	glaciers

Humanitarian data

	Provider	data_source
	Humanitarian Data Exchange (UN OCHA)	hdx

Hydrology

	Provider	data_source
	NOAA National Water Model	nwm
	USGS National Water Information System	usgs-water

Multi-mission imagery & data platforms

	Provider	data_source
	AWS Open Data	amazon-s3
	EUMETSAT	eumetsat
	Google Earth Engine	gee
	JAXA	jaxa
	NASA Earthdata	earthdata
	NOAA GOES-R	goes
	STAC (SpatioTemporal Asset Catalog)	stac
	Sentinel Hub	sentinel-hub
	openEO	openeo

Ocean

	Provider	data_source
	Argo Program	argo
	Copernicus Marine Service	cmems
	NOAA ERDDAP	erddap

Population & human settlement

	Provider	data_source
	European Commission Joint Research Centre (GHSL)	ghsl
	WorldPop	worldpop

Precipitation & drought

	Provider	data_source
	Climate Hazards Center (UCSB)	chc
	Copernicus European Drought Observatory / NDMC	drought

Renewable energy

	Provider	data_source
	Global Solar Atlas / Global Wind Atlas (World Bank/ESMAP)	solar-wind-atlas
	National Laboratory of the Rockies (formerly NREL)	nrel
	PVGIS (EU JRC)	pvgis

SAR / radar imagery

	Provider	data_source
	Alaska Satellite Facility (ASF)	asf

Soil

	Provider	data_source
	ISRIC SoilGrids	soilgrids

Tropical cyclones

	Provider	data_source
	Tropycal	tropycal

Vector basemaps & boundaries

	Provider	data_source
	OpenStreetMap	osm
	Overture Maps Foundation	overture
	geoBoundaries	admin

Weather forecast (NWP)

	Provider	data_source
	Herbie (NWP archive access)	nwp

Weather radar

	Provider	data_source
	NOAA NEXRAD	radar

Logos are each provider's own mark, used only to identify which service a backend talks to (not an endorsement of earthlens by that provider) — see docs/_images/logos/ATTRIBUTION.md for sourcing and rights notes on every logo, including the handful of providers with no distinct mark of their own.

Installation

earthlens is published on conda-forge and PyPI.

# conda (recommended — pulls GDAL automatically)
conda install -c conda-forge earthlens

# pip — latest release
pip install earthlens==0.3.0

# pip — bleeding edge
pip install git+https://github.com/serapeum-org/earthlens

To list all available versions on your platform:

conda search earthlens --channel conda-forge

GDAL is required and is not on PyPI. If you install via pip, get GDAL from the large-image-wheels index:

pip install --find-links=https://girder.github.io/large_image_wheels --no-cache GDAL==3.10.0

Backend SDKs are optional and pulled in by extras:

pip install earthlens[ecmwf]   # cdsapi
pip install earthlens[s3]      # boto3 + unicloud
pip install earthlens[gee]     # earthengine-api
pip install earthlens[dev,test]  # full dev environment

Quick examples per backend

CHIRPS daily rainfall — anonymous FTP, no credentials.

from earthlens.core import EarthLens

EarthLens(
    data_source="chc",
    temporal_resolution="daily",
    start="2009-01-01",
    end="2009-01-10",
    variables=["precipitation"],
    lat_lim=[4.19, 4.64],
    lon_lim=[-75.65, -74.73],
    path="data/chirps",
).download(cores=4)  # parallel FTP fetch

ERA5 monthly via AWS public S3 — unsigned, fast, no API key.

EarthLens(
    data_source="amazon-s3",
    temporal_resolution="monthly",
    start="2020-01-01",
    end="2020-12-01",
    variables=["air_temperature_at_2_metres", "precipitation_amount_1hour_Accumulation"],
    lat_lim=[30.0, 35.0],
    lon_lim=[28.0, 35.0],
    path="data/era5-s3",
).download()

ECMWF CDS with on-the-fly aggregation. Downloads daily ERA5, then writes monthly GeoTIFFs aggregated with the right reduction per variable (mean for temperature, sum for precipitation):

from earthlens.core import EarthLens, AggregationConfig

EarthLens(
    data_source="ecmwf",
    temporal_resolution="daily",
    start="2022-06-01",
    end="2022-08-31",
    variables={
        "reanalysis-era5-single-levels": [
            "2m-temperature",
            "total-precipitation",
        ],
    },
    lat_lim=[37.0, 38.0],
    lon_lim=[23.0, 24.0],
    path="data/athens-summer",
).download(aggregate=AggregationConfig(freq="1MS", op="auto"))

Google Earth Engine — server-side collection, downloaded as GeoTIFFs.

EarthLens(
    data_source="gee",
    temporal_resolution="daily",
    start="2023-01-01",
    end="2023-01-10",
    variables=["MODIS/061/MOD13Q1/NDVI"],
    lat_lim=[30.0, 31.0],
    lon_lim=[31.0, 32.0],
    path="data/gee-ndvi",
).download()

Aggregation: state vs flux

ERA5 mixes two physically distinct kinds of variables:

• State variables are instantaneous samples — temperature, SST, soil moisture, snow depth. Aggregating in time means averaging.
• Flux variables are accumulated over each timestep — precipitation, radiation, evaporation, surface heat fluxes. Aggregating in time means summing.

Mixing those up produces silently wrong results (a "monthly mean" of precipitation under-reports rainfall by ~30×). earthlens's catalog tags every variable with is_flux, and op="auto" reads that flag to pick the right reduction:

from earthlens.ecmwf import Catalog
spec = Catalog().get_variable(
    "reanalysis-era5-single-levels", "total-precipitation"
)
print(spec.is_flux)  # True  -> auto-aggregate by SUM

You can override with op="mean" | "sum" | "max" | "min" when you know better than the catalog.

Authentication

Documentation

Full docs, API reference, architecture diagrams, and a gallery of domain-specific example notebooks (hydrology, oceanography, agriculture, solar/wind energy, heat waves, drought, snow & cryosphere, climate-change anomalies) live at:

https://serapeum-org.github.io/earthlens/

Contributing

Issues, PRs, and discussions are welcome on GitHub. The repo uses pre-commit (black, isort, flake8, bandit, pydocstyle) — install hooks once with pre-commit install.

License

GPL v3. See LICENSE.