earthlens is designed following the Template/Factory design pattern to create an abstract class as a template for different data sources.
The main objective is to provide a unified API for all remote sensing data sources, where you only have to worry about the domain of your data (date range and spatial extent) and the package does everything in the backend.
earthlens provides a unified API across 61 providers — see All supported providers
below for the full index, or jump straight to a provider's own reference page
(docs/reference/<id>/introduction.md) for its full walkthrough.
Note
Many data sources (Google Earth Engine, ECMWF, EUMETSAT, Sentinel Hub, …) require authentication keys. See the Authentication page for setup instructions, or each provider's own reference page for provider-specific credential details.
The API takes a few parameters to determine the domain of your data:
Date range: start, end, and temporal_resolution
Spatial extent: lat_lim (latitude limits) and lon_lim (longitude limits)
If lat_lim and lon_lim are not provided, the EarthLens class defaults to longitude [-180, 180] and latitude [-90, 90].
Each data source has different climate variables/datasets. To discover available variables, use the Catalog class for each data source (see Data Catalog).
Info
The downloaded data format differs based on the data source. CHIRPS and ECMWF have a post_download function that converts the NetCDF format into GeoTIFF using the pyramids GIS package.
Note
In future versions, lat_lim and lon_lim will be deprecated and replaced by a GeoDataFrame containing a polygon geometry.
Each provider's id links to its own reference page for the full walkthrough, authentication details, and catalog. Pass the data_source value to EarthLens(...).
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.
The ECMWF backend talks to the Copernicus Climate Data Store via
cdsapi. ERA-Interim was retired in 2019 and the public-datasets
endpoint that hosted it was decommissioned in 2023; ERA5 on CDS is
the production successor and what every ECMWF retrieve in this
package now hits. Set up your ~/.cdsapirc first
(see Authentication) and accept the licence for
the relevant ERA5 dataset on the CDS website.
source="ecmwf"path="examples/data/era5"# Variables are addressed by (CDS dataset short name, variable code).variables={"reanalysis-era5-single-levels":["2m-temperature"],}earthlens=EarthLens(data_source=source,start=start,end=end,variables=variables,lat_lim=latlim,lon_lim=lonlim,temporal_resolution=temporal_resolution,path=path,)earthlens.download()
Expect to wait
client.retrieve() blocks until the request reaches the front of
the CDS queue and the file is generated — typically minutes,
occasionally longer for large requests. Pick a small bbox and date
range to keep wait times bearable. In CI the cdsapi client is
mocked; the live end-to-end suite is selected with pytest -m e2e.
