Providers

easysnowdata.providers

Thin, generic adapters over the access libraries — no snow knowledge here.

• stac — pystac-client + odc-stac (Planetary Computer, Earth Search, CMR-STAC)

• opentopography — OpenTopography’s static STAC catalog of public COGs (no search API; tiles picked by asset bbox)

• earthdata — earthaccess search / open / download

• gee — Earth Engine via xee at the native grid

• planet — Planet Data and Orders APIs via the planet SDK

• raster_http — COGs and zipped GeoTIFFs over HTTPS, with a pooch cache

• zarr_cloud — anonymous cloud Zarr stores

• vector_http — remote GDB / GeoJSON / GeoParquet with bbox or mask pushdown

• table_http — small text tables (climate-index files) over HTTPS, re-fetched when the cached copy is a day old

Every read happens inside easysnowdata._gdal.gdal_env() (and the auth providers’ env()); nothing here configures GDAL, xarray or “today” at import time (§2.9).

gdal_env

Apply GDAL options for the duration of the block (and to lazy reads).

easysnowdata.providers.stac

STAC search and load: pystac-client for search, odc-stac for lazy loading.

open_catalog	Open a STAC API by name ("planetary-computer", "earth-search", "cmr-lpcloud", "cmr-asf", "cmr-nsidc") or URL.
search	Search a STAC API and return a pystac.ItemCollection.
items_to_geodataframe	Items → GeoDataFrame (EPSG:4326) with id, collection, datetime, the item properties as columns, and the full item dict in stac_item so load() can take a filtered frame back.
geodataframe_to_items	Rebuild pystac.Item objects from a frame made by items_to_geodataframe().
load	Lazily load STAC items into an xarray.Dataset with odc-stac.
odc_load	odc.stac.load with the read environment applied (a low-level helper for callers that build their own load_params).
read_env	GDAL + credential environment for reading assets found in catalog.

easysnowdata.providers.earthdata

NASA Earthdata via earthaccess: search, open, download (cached).

ensure	Log in (once) and return the earthaccess.Auth.
env	GDAL environment for /vsicurl reads of EDL-protected files.
search	earthaccess.search_data with the package's AOI/time inputs.
granules_to_geodataframe	Granules → GeoDataFrame: id, start, end, size_mb, data_links, geometry.
open	earthaccess.open (fsspec file objects) after an explicit login.
download	earthaccess.download into the easysnowdata cache (<cache>/<subdir>).
download_with_password	Download one file from a server that refuses a bearer token.
auth_host_in	Whether url is on the Earthdata Login host (a request that ended at the login page).
hdf4_available	Whether this GDAL build can read HDF4 (HDF-EOS2) files.
require_hdf4	Fail fast when product is HDF4 and GDAL has no HDF4 driver.

easysnowdata.providers.gee

Google Earth Engine via xee: open at the native grid, features → GeoDataFrame.

import ee and import xee are deferred so a broken Google auth stack cannot break import easysnowdata. Earth Engine is initialised once through easysnowdata.auth; Dask workers re-initialise themselves through ee_init_if_necessary / ee_init_kwargs.

ensure	Initialise Earth Engine once (see the earthengine auth provider).
ee	Return the initialised ee module.
grid_params	Pixel-grid kwargs for xarray.open_dataset(engine="ee").
open_dataset	xarray.open_dataset(engine="ee") at the native grid cropped to aoi.
features_to_geodataframe	An ee.FeatureCollection (or asset id) → GeoDataFrame, filtered to aoi.
geometry	An ee.Geometry for the AOI footprint (EPSG:4326, geodesic=False).

easysnowdata.providers.opentopography

OpenTopography’s raster catalog: a static STAC catalog of public COGs.

OpenTopography publishes its whole raster library — the global DEMs and the community lidar surveys — as a static STAC 1.1 catalog (CATALOG_URL), with the tiles as anonymous Cloud Optimized GeoTIFFs on SDSC’s S3-compatible store (BUCKET_URL). No account, no signing.

It is not a STAC API: there is no /search endpoint, so pystac-client cannot query it. Each dataset is one collection holding one item per product level (COP30_hh, SRTM_GL1_srtm, NASADEM_be), and every tile of that dataset is an asset of the one item, with its own bbox. The Copernicus GLO-30 item is 12 MB of JSON with about 26 000 assets. search() therefore downloads the item once into the cache (re-fetched after MAX_AGE), picks the assets whose bbox meets the AOI, and turns each into a pystac.Item that odc-stac can load. The assets carry no proj: metadata, so the grid of each selected tile is read from its COG header (one small range request per tile, in parallel).

Two more quirks worth knowing: an item’s datetime is when OpenTopography processed the dataset, not when it was acquired, so the items built here take their dates from the collection’s temporal extent instead; and each item also lists a <item>.vrt mosaic of all its tiles (11 MB for Copernicus), which this module does not use.

collection_id	The collection an item belongs to: "COP30_hh" → "COP30".
collection_url	URL of the collection JSON for a short name such as "SRTM_GL1".
item_url	URL of the item JSON for an id such as "SRTM_GL1_srtm".
collection	The collection JSON for a short name ("COP30"), from the cache.
item	The item JSON for an id ("COP30_hh"), from the cache.
tiles	The data assets of item_id whose bbox meets aoi.
search	The tiles of item_id covering aoi as a pystac.ItemCollection.

easysnowdata.providers.planet

Planet Labs via the planet SDK 3.x: Data API search, Orders API delivery.

Thin and generic, like the other providers: it knows how to talk to Planet, not what PlanetScope is. The snow knowledge lives in easysnowdata.optical.planetscope.

Everything goes through one planet.Planet client built by the planet auth provider (easysnowdata.auth.planet), which delegates credential detection and login to the SDK’s own stack. Nothing here configures GDAL: the APIs hand out signed download URLs.

Quota. A Data API search is free. Activating a Data API asset charges the whole scene against the account’s quota, and an order charges the clipped area, which is why create_order() refuses to run without an AOI and why ordering is never part of a test.

ensure	Return the process-wide planet.Planet client, logging in if needed.
client	Alias of ensure(), for symmetry with the other providers.
sdk	Return the imported planet module (a required dependency).
build_search_filter	Build a Data API search_filter from the package's AOI/time inputs.
search	Run a Data API quick-search and return the items as dicts (free).
items_to_geodataframe	Data API items → GeoDataFrame with id, item_type, acquired and the item properties as columns (the same shape every search_* returns).
product	One products entry of an order request.
create_order	Create an Orders API order clipped to aoi, and return the order dict.
find_order	Return the newest order called name (in state, if given), or None.
wait_order	Block until an order reaches a final state and return that state.
download_order	Download a finished order into the easysnowdata cache and return the paths.
asset_url	Return a signed download URL for one asset of one scene.

easysnowdata.providers.raster_http

COGs and zipped GeoTIFFs over HTTPS (rioxarray), plus a pooch download cache.

open	Open a raster with rioxarray.open_rasterio inside the read environment.
zip_url	GDAL path for member inside the zip at url.
fetch	Download url once into the cache with a plain GET and return the local path.

easysnowdata.providers.zarr_cloud

Anonymous cloud Zarr stores (GCS, S3, Azure, HTTPS) with xarray.

storage_options_for	Anonymous-access storage_options for the store's scheme.
open	xarray.open_zarr with anonymous defaults for public buckets.
select	Subset a global lat/lon dataset to an AOI and time range.

easysnowdata.providers.vector_http

Remote vectors (GDB, GeoJSON, zipped shapefiles, GeoParquet) with pyogrio pushdown.

read	geopandas.read_file with AOI pushdown inside the read environment.
read_parquet	geopandas.read_parquet with bbox pushdown from the AOI (GeoParquet 1.1 bbox column).
zip_path	GDAL/fiona-style zip path: zip+https://…!member or zip:///local.zip!member.

easysnowdata.providers.table_http

Small text tables over HTTPS (climate-index files), cached with pooch.

The files are a few kilobytes and are republished in place every month, so they are downloaded whole with a plain GET and re-fetched once the cached copy is older than max_age. Parsing is the product module’s job; this layer only moves bytes, like the other providers.

fetch

Download url into the cache and return the local path.