Installable package foundation, Python client, and User-facing docs

.env.example

@@ -1,36 +1,54 @@
-PYGEOAPI_CONFIG=data/pygeoapi/pygeoapi-config.yml
-PYGEOAPI_OPENAPI=data/pygeoapi/pygeoapi-openapi.yml
-
-# DHIS2 Connection
-DHIS2_BASE_URL=https://play.im.dhis2.org/stable-2-42-4/api
-DHIS2_USERNAME=admin
-DHIS2_PASSWORD=district
-
-# CDS API (required for ERA5-Land downloads)
-# Get your API key from: https://cds.climate.copernicus.eu/how-to-api
-CDSAPI_URL=https://cds.climate.copernicus.eu/api
-CDSAPI_KEY=your-cds-api-key
-
-# Download cache directory for climate data
-# DOWNLOAD_DIR=./target/data
-
-# Default EO download extent when a dataset requires bbox and the request does not provide one
+# ── Instance configuration ────────────────────────────────────────────────────
+# Path to the instance config file (extent, optional datasets_dir).
+# Copy the example before editing: cp climate-api.yaml.example climate-api.yaml
+# climate-api.yaml is gitignored so your local extent stays out of version control.
+# When running via `make run` from the repo root, the relative path below works.
+# When running the installed `climate-api` CLI from another directory, use an
+# absolute path instead: CLIMATE_API_CONFIG=/path/to/your/climate-api.yaml
+CLIMATE_API_CONFIG=./climate-api.yaml
+
+# ── pygeoapi ──────────────────────────────────────────────────────────────────
+# Absolute paths are set automatically at startup; override only if you move the files.
+# PYGEOAPI_CONFIG=/absolute/path/to/pygeoapi-config.yml
+# PYGEOAPI_OPENAPI=/absolute/path/to/pygeoapi-openapi.yml
+
+# ── ERA5-Land (DestinE Earth Data Hub) ────────────────────────────────────────
+# Authentication uses ~/.netrc — no API key is required here.
+# See docs/setup_guide.md for registration and .netrc setup instructions.
+
+# ── Download and ingestion ────────────────────────────────────────────────────
+# Override the download cache directory (default: data/downloads).
+# CACHE_OVERRIDE=/path/to/cache
+
+# Fallback bounding box used when a request does not include an explicit bbox.
 # Format: xmin,ymin,xmax,ymax
 # DOWNLOAD_BBOX=-13.5,6.9,-10.1,10.0
 
-# Default country code for datasets that require one (for example WorldPop)
+# Country code for datasets that require one (e.g. WorldPop).
 # COUNTRY_CODE=SLE
 
-# OGC API base URL (used by Prefect tasks to call back into the API)
-# OGCAPI_BASE_URL=http://localhost:8000/ogcapi
-
-# Public Climate API base URL used for absolute STAC links behind a reverse proxy
+# ── API deployment ────────────────────────────────────────────────────────────
+# Set when running behind a reverse proxy so that STAC hrefs and native dataset
+# links use the public address instead of the internal request URL.
+# Note: pygeoapi's OGC self/root links are controlled separately via server.url
+# in config/pygeoapi/base.yml and are not affected by this variable.
 # CLIMATE_API_BASE_URL=http://localhost:8000
 
-# TiTiler tile server base URL
-# TITILER_BASE_URL=http://127.0.0.1:8000
+# Fallback used to derive the native API base URL when CLIMATE_API_BASE_URL is not set.
+# Only needed if CLIMATE_API_BASE_URL is unset and the OGC API path is known.
+# Note: pygeoapi's server.url is controlled separately in config/pygeoapi/base.yml.
+# OGCAPI_BASE_URL=http://localhost:8000/ogcapi
 
-# Prefect (embedded server)
-PREFECT_API_URL=http://localhost:8000/prefect/api
-PREFECT_SERVER_ANALYTICS_ENABLED=false
-PREFECT_SERVER_UI_SHOW_PROMOTIONAL_CONTENT=false
+# Comma-separated list of origins used for extra browser/private-network headers
+# on Zarr responses (default: https://inspect.geozarr.org).
+# This does not restrict general CORS access; the API allows all origins globally.
+# CLIMATE_API_ZARR_BROWSER_ORIGINS=http://localhost:3000
+
+# ── DHIS2 connection ──────────────────────────────────────────────────────────
+# Required for DHIS2 org unit lookups (Step 2 — spatial aggregation).
+# Not needed for Step 1 (data ingestion, sync, and serving).
+# DHIS2_BASE_URL=https://play.im.dhis2.org/stable-2-42-4/api
+# DHIS2_USERNAME=admin
+# DHIS2_PASSWORD=district
+# DHIS2_HTTP_TIMEOUT_SECONDS=30
+# DHIS2_HTTP_RETRIES=3

.gitignore

@@ -2,6 +2,7 @@
 __pycache__/
 .venv/
 .env
+climate-api.yaml
 eo_api.egg-info/
 data/downloads
 data/artifacts

CLAUDE.md

@@ -8,7 +8,7 @@ Key concepts:
 
 - **Dataset templates** — YAML files in `data/datasets/` describing a data source (variable, period type, download function). These are blueprints.
 - **Artifacts / managed datasets** — ingested instances of a template for a specific spatial extent and time range. Exposed under `/datasets` and `/zarr/{dataset_id}`.
-- **Extents** — named spatial bounding boxes configured at instance setup time (`id`, `bbox`, optional `country_code`).
+- **Extent** — a single named spatial bounding box configured at instance setup time (`id`, `bbox`, optional `country_code`). Exposed at `GET /extent`.
 
 ## Repository layout
 
@@ -41,11 +41,11 @@ The `.env` file is required for `make run` and `make openapi`. Copy `.env.exampl
 
 ## Dataset templates
 
-Each YAML in `data/datasets/` defines a dataset template. The `cache_info` block controls download and zarr build behaviour:
+Each YAML in `data/datasets/` defines a dataset template. The `ingestion` block controls download and zarr build behaviour:
 
 ```yaml
-cache_info:
-  eo_function: dhis2eo.data.worldpop.pop_total.yearly.download
+ingestion:
+  function: dhis2eo.data.worldpop.pop_total.yearly.download
   default_params: {} # passed to the download function
   multiscales: # optional — triggers pyramid build
     levels: 4

README.md

@@ -4,7 +4,7 @@ Climate and Earth Observation data is distributed across dozens of providers —
 
 Each instance is configured for a specific country or region, and all data extraction, processing, and storage is scoped to that spatial extent. It abstracts data access across heterogeneous sources (CHIRPS, ERA5, WorldPop, and others), stores outputs as GeoZarr, and exposes them through standards-based endpoints.
 
-The platform is designed to operate independently of DHIS2 and can be deployed on local, cloud-hosted, or sovereign country infrastructure. See [docs/project_description.md](docs/project_description.md) for a full description of the vision and technical architecture, [docs/managed_data_api_guide.md](docs/managed_data_api_guide.md) for the current API surface, and [docs/roadmap.md](docs/roadmap.md) for the planned development steps.
+The platform is designed to operate independently of DHIS2 and can be deployed on local, cloud-hosted, or sovereign country infrastructure. See [docs/setup_guide.md](docs/setup_guide.md) for a step-by-step setup walkthrough, [docs/user_guide.md](docs/user_guide.md) for data access examples, [docs/managed_data_api_guide.md](docs/managed_data_api_guide.md) for the full API reference, and [docs/roadmap.md](docs/roadmap.md) for the planned development steps.
 
 > **Status: active development.** Current focus is on dataset ingestion, sync workflows, and GeoZarr storage. APIs and data models may change without notice.
 
@@ -18,13 +18,7 @@ Install dependencies (requires [uv](https://docs.astral.sh/uv/)):
 uv sync
 ```
 
-Copy `.env.example` to `.env` and adjust values as needed. Environment variables are loaded automatically from `.env` at runtime.
-
-Key environment variables:
-
-- `DHIS2_BASE_URL` — DHIS2 API base URL (defaults to play server in `.env.example`)
-- `DHIS2_USERNAME` — DHIS2 username
-- `DHIS2_PASSWORD` — DHIS2 password
+Copy `.env.example` to `.env` and adjust values as needed. Environment variables are loaded automatically from `.env` at runtime. See `.env.example` for the full list of available options.
 
 Start the app:
 
@@ -40,7 +34,7 @@ If you cannot use uv (e.g. mixed conda/forge environments):
 python -m venv .venv
 source .venv/bin/activate
 pip install -e .
-uvicorn climate_api.main:app --reload
+python -m uvicorn climate_api.main:app --reload
 ```
 
 ### Using conda
@@ -49,7 +43,7 @@ uvicorn climate_api.main:app --reload
 conda create -n dhis2-climate-api python=3.13
 conda activate dhis2-climate-api
 pip install -e .
-uvicorn climate_api.main:app --reload
+python -m uvicorn climate_api.main:app --reload
 ```
 
 ## Development
@@ -73,33 +67,43 @@ Once running, the API is available at:
 
 | Endpoint                                  | Description                                |
 | ----------------------------------------- | ------------------------------------------ |
-| `http://localhost:8000/`                  | Welcome / health check                     |
+| `http://localhost:8000/`                  | Navigation document                        |
+| `http://localhost:8000/health`            | Health check                               |
 | `http://localhost:8000/docs`              | Interactive API documentation (Swagger UI) |
+| `http://localhost:8000/extent`           | Configured spatial extent                  |
+| `http://localhost:8000/datasets`          | Managed dataset catalogue                  |
 | `http://localhost:8000/stac/catalog.json` | STAC catalog for published GeoZarr data    |
+| `http://localhost:8000/zarr/{dataset_id}` | GeoZarr store for a managed dataset        |
 | `http://localhost:8000/ogcapi`            | OGC API root                               |
-| `http://localhost:8000/zarr/{dataset_id}` | GeoZarr store for a published dataset      |
 
 ## STAC
 
-Published Zarr-backed managed datasets are exposed under `/stac` as one STAC Collection per dataset.
+Published GeoZarr datasets are discoverable under `/stac` as one STAC Collection per dataset. Each collection includes a `zarr` asset with direct xarray-compatible access metadata derived from the live Zarr store.
 
-- `/stac/catalog.json` is the entrypoint catalog
-- `/stac/collections/{dataset_id}` exposes a Collection with a direct `/zarr/{dataset_id}` asset href
-- `xstac` derives Datacube metadata from the real Zarr-backed dataset
-- `pygeoapi` remains the OGC query layer under `/ogcapi`
+Discover available datasets and open one with xarray:
 
-Minimal example:
+The catalog is populated once at least one dataset has been ingested and published (see [docs/setup_guide.md](docs/setup_guide.md)).
 
 ```python
-import requests
+import httpx
 import xarray as xr
 
-collection = requests.get(
-    "http://127.0.0.1:8000/stac/collections/chirps3_precipitation_daily_sle"
-).json()
-
-asset = collection["assets"]["zarr"]
-ds = xr.open_zarr(asset["href"], consolidated=asset["xarray:open_kwargs"]["consolidated"])
+catalog = httpx.get("http://127.0.0.1:8000/stac/catalog.json").json()
+children = [link for link in catalog["links"] if link["rel"] == "child"]
+
+if not children:
+    print("No published datasets found. Run an ingestion first.")
+else:
+    for link in children:
+        print(link["title"], "—", link["href"])
+
+    collection = httpx.get(children[0]["href"]).json()
+    asset = collection["assets"]["zarr"]
+    ds = xr.open_zarr(
+        asset["href"],
+        consolidated=asset["xarray:open_kwargs"]["consolidated"],
+    )
+    print(ds)
 ```
 
 ## pygeoapi

climate-api.yaml.example

@@ -0,0 +1,11 @@
+# Climate API instance configuration.
+# Replace the extent below with your country before deploying.
+# See docs/setup_guide.md for field descriptions.
+
+extent:
+  id: sle
+  name: Sierra Leone
+  bbox: [-13.5, 6.9, -10.1, 10.0]
+  country_code: SLE
+
+# datasets_dir: ./datasets/   # optional — custom templates merged with built-ins