| Name | Downloads | Version | Platforms |
|---|---|---|---|
 |
   |
   |
 |
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.
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.
- 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 withCatalog().get_variable(...). - Pre-flight request validation against the live CDS
constraints.jsongraph. Bad date / area / variable combinations are rejected before bytes go over the wire, with actionable error messages. - Temporal aggregation built in. Pass an
AggregationConfigtodownload()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-gisunder 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.
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.
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/earthlensTo list all available versions on your platform:
conda search earthlens --channel conda-forgeGDAL 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.0Backend 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 environmentCHIRPS 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 fetchERA5 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()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 SUMYou can override with op="mean" | "sum" | "max" | "min" when you know
better than the catalog.
| Source | What you need |
|---|---|
| CHIRPS | Nothing — anonymous FTP. |
| Amazon S3 | Nothing — unsigned, public bucket. |
| ECMWF / CDS | A free CDS account and a ~/.cdsapirc with your API key. |
| GEE | A Google Earth Engine project and a service-account JSON key. |
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:
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.
GPL v3. See LICENSE.