spatioClimata 0.1.0

Copernicus climate and hydrology data pipeline toolkit with analytics-ready outputs.

spatioClimata

spatioClimata is a Python package for requesting, validating, downloading, and transforming Copernicus climate and hydrology datasets into analytics-ready outputs.

It is designed for ERA5, GloFAS, and extensible CDS/EWDS datasets, with an opinionated data engineering pipeline and optional Dask acceleration.

Why spatioClimata

• Unified access to CDS and EWDS with one API key workflow.
• Dataset capability checks before large downloads.
• Hourly and daily workflows with optional frequency conversion.
• Resumable, idempotent download pipeline for long-running jobs.
• Analytics-ready outputs as xarray Dataset with NetCDF/Zarr export.
• Optional Dask integration for chunked processing at scale.

Installation

pip install spatioClimata

For Dask-enabled workflows:

pip install "spatioClimata[dask]"

For development:

pip install "spatioClimata[dev,dask]"

Quick Start

from spatioclimata import (
    AreaBBox,
    TimeRange,
    FetchRequest,
    fetch,
)

request = FetchRequest(
    dataset="derived-era5-single-levels-daily-statistics",
    variables=["total_precipitation", "2m_temperature"],
  time_range=TimeRange.from_strings("2020-01-01", "2020-12-31"),
  area=AreaBBox.from_sequence([6.22, 80.41, 5.91, 80.64]),
    frequency="daily",
    output_dir="./outputs",
)

result = fetch(request, open_browser_on_missing_key=True)
print(result.saved_files)

CLI Usage

Initialize credentials:

spatioclimata auth init --open-browser

List datasets:

spatioclimata datasets list

Run a download:

spatioclimata fetch \
  --dataset derived-era5-single-levels-daily-statistics \
  --variables total_precipitation,2m_temperature \
  --start 2020-01-01 \
  --end 2020-12-31 \
  --area 6.22,80.41,5.91,80.64 \
  --frequency daily \
  --output-dir ./outputs

Account and API Key Onboarding

The package needs a Copernicus API key.

• spatioclimata auth init --open-browser opens signup and API key pages.
• Credentials are saved to a local config file with restricted permissions when possible.
• Environment variables are also supported:
  • SPATIOCLIMATA_API_KEY
  • ERA5_Key

Project Layout

• src/spatioclimata/: package source
• tests/: unit tests
• examples/: runnable usage examples
• docs/: architecture and usage guides
• .github/workflows/: CI
• website/: static project website (GitHub Pages source)
• scripts/: helper scripts for repo bootstrap, website sync, and releases

Documentation Index

• Quickstart
• Architecture
• Pipeline Guide
• Dataset Support
• Release and Deploy

Status

Current release is an MVP foundation intended to be expanded with additional dataset adapters and transformations.

Release and Deployment

PyPI Publish

• Workflow: .github/workflows/publish-pypi.yml
• Trigger: push a version tag (example: v0.1.0)
• Recommended: configure PyPI Trusted Publishing for this repository

Website Deploy

• Workflow: .github/workflows/deploy-pages.yml
• Source folder: website/
• Trigger: push to main when website files change
• GitHub setting required: enable GitHub Pages with "GitHub Actions" as source

License

MIT