Current release info
| Name |
Downloads |
Version |
Platforms |
 |
      |
   |
 |
earthlens — a unified Python client for satellite & climate data
34 of the spacecraft behind earthlens' providers, on their published orbits. The trailing band under
each one is its instrument's real ground swath, and the trapezoid above it is the sensor footprint sweeping
that strip out.
The clock counts simulated orbital time at 270× real, so 20 seconds of clip is 1.5 hours in
orbit. Earth turns 22.6° in that window and a low orbiter gets about nine tenths of the way round —
which is how you read its ~90-minute period straight off the screen. The geostationary satellites look
frozen because they are keeping pace with the ground beneath them.
earthlens gives you one consistent Python API for downloading satellite,
climate, and geospatial data from 61 providers — climate reanalysis,
satellite imagery, ocean models, weather forecasts, natural-hazard feeds, air
quality, biodiversity, population, and more — and turning the results into
analysis-ready GeoTIFFs, GeoDataFrames, or tables.
It is part of the serapeum-org
open-source ecosystem and is built on top of
pyramids-core for raster I/O.
Why earthlens?
Every 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,
Google Earth Engine is a server-side image-collection model, and the other 44
each have their own. earthlens flattens all of it 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
- 61 backends, one facade.
EarthLens(data_source=...) routes to any
provider without changing the rest of your code. Backends are discovered
through entry points and imported lazily, so the SDK for a provider you never
touch is never loaded.
- Cross-provider discovery.
find("precipitation") tells you which of the
61 providers serve a dataset, offline, before you commit to one; search(...)
dry-runs a request and lists exactly what it would fetch.
- YAML variable catalogs per provider — 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-core
under the hood.
- Modular install extras — only install the SDK for the backend you need
(
pip install earthlens[ecmwf], [s3], [gee]).
- Bounded by design. Streamed, atomic downloads; pooled HTTP connections
with
Retry-After-aware back-off; an exact limit= cap for vector/tabular
requests; re-runs skip artefacts that are already complete.
- Strictly typed. Pydantic v2 models for catalog rows and request specs;
modern PEP 585/604 type hints; Python 3.11 – 3.14 tested in CI.
Supported data sources
earthlens wraps 61 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
Biodiversity & protected areas
Climate reanalysis & projections
Disasters & risk
Elevation & bathymetry
Glaciers & cryosphere
Humanitarian data
Hydrology
Multi-mission imagery & data platforms
Ocean
Population & human settlement
Precipitation & drought
Renewable energy
SAR / radar imagery
Soil
Tropical cyclones
Vector basemaps & boundaries
Weather forecast (NWP)
Weather 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.
# pip — latest release
pip install earthlens
# conda
conda install -c conda-forge earthlens
# 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
A plain pip install is enough — earthlens pulls in everything it needs.
Backend SDKs are optional and pulled in by extras:
pip install earthlens[ecmwf] # cdsapi
pip install earthlens[s3] # boto3 + botocore
pip install earthlens[gee] # earthengine-api
pip install earthlens[all] # every backend SDK
[all] deliberately omits argo (and eedai): argopy requires xarray>=2025.7
while openeo (which is in all) caps xarray<2025.1.2. osm is included and
covers all three protocols — overpy/ohsome plus the wheel-clean osmium (pyosmium) for
bulk .osm.pbf reads. The richer in-memory pyrosm pbf engine is opt-in (pip install pyrosm, which builds the sdist-only cykhash from source). See
what [all] excludes.
For a development environment the repo is a uv
workspace — dev and docs are dependency groups, not extras:
uv sync --extra all --group dev
See Contributing for
the full setup.
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. The
request is {asset_id: [band, ...]}, and GEE needs a service account:
EarthLens(
data_source="gee",
temporal_resolution="monthly", # one composite image per month
start="2020-06-01",
end="2020-08-31",
variables={"UCSB-CHG/CHIRPS/DAILY": ["precipitation"]},
lat_lim=[28.0, 32.0],
lon_lim=[30.0, 34.0],
path="data/gee",
scale=5566, # output pixel size in metres
).authenticate(
service_account="[email protected]",
service_key="/path/to/key.json",
).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
Roughly half the backends need no credentials at all. Common ones:
| Source |
What you need |
| CHIRPS / CHC |
Nothing — anonymous FTP. |
| Amazon S3, Copernicus DEM, GOES, NWM, NEXRAD |
Nothing — unsigned, public buckets. |
| GDACS, GHSL, Overture, HDX, SoilGrids, PVGIS, admin |
Nothing — public HTTP. |
| 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. |
| CMEMS, Earthdata, ASF, EUMETSAT, Sentinel Hub, openEO |
A provider login. |
| OpenAQ, AirNow, FIRMS, WDPA, IUCN, NREL, GFW |
A free API key or token. |
Where credentials go is backend-specific: some take them as constructor keywords (CMEMS’s
service_username= / service_password=), others in authenticate(...) (GEE’s service_account=, FIRMS’s
api_key=), and most fall back to an environment variable. Each backend’s page says which. The full
per-provider matrix is in
Supported providers.
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/
Start here:
Contributing
Issues, PRs, and discussions are welcome on
GitHub. The repo uses pre-commit
with ruff (ruff-check + ruff-format), mypy, and bandit — install the
hooks once with pre-commit install.
See the contributing guide
for the workspace layout, how to run the tests, and how to add a new provider
backend.
License
GPL v3. See LICENSE.
评论