Weather API

A FastAPI service that serves HRRR (High-Resolution Rapid Refresh) weather-model data for the contiguous US via a point, bounding-box, state, and time-range HTTP interface. Built at the UW-Madison Data Science Institute.

What it does

1. Get a (time-series) slice of HRRR data for your area of interest in one authenticated API call.
2. Automatically reproject results into the coordinate reference system (EPSG) you're working in.
3. Automatically derive WSPD (wind speed) and WDIR (wind direction) from the raw UGRD/VGRD wind components.

Under the hood it is a caching proxy: data is fetched once from the public HRRRZarr S3 archive, stored as GeoTIFFs in a private S3 bucket, indexed in PostGIS, and served on subsequent requests. Requests for already-cached data return 200 with inline data; requests that need a fetch return 202 with a job you poll and then download.

---

Documentation

Full documentation lives in docs/. Start here:

If you want to…	Read
Inherit / maintain this project	docs/HANDOFF.md ⭐
Stand up a local instance & make your first call	docs/getting-started/quickstart.md
Get and use an API key	docs/getting-started/obtaining-api-keys.md
Call the API (endpoints, params, examples, errors)	docs/end-user/api-reference.md
Know the coverage, limits, and failure modes	docs/end-user/capabilities-and-limits.md
Administer users & keys (admin UI)	docs/end-user/web-ui-guide.md
Understand the architecture	docs/developer/architecture-overview.md
Find your way around the code	docs/developer/codebase-map.md
Deploy it	docs/developer/deployment-guide.md
Operate it (caching, backups, incidents)	docs/operations/runbook.md
Look up unfamiliar terms (HRRR, Zarr, CRS…)	docs/end-user/glossary.md

---

Quick start (local)

Requires Docker. See the full quickstart for detail, including how to obtain an API key.

git clone git@github.com:UW-Madison-DSI/weather_api.git
cd weather_api
cp example.env .env        # then fill in credentials — see the deployment guide
docker compose -f docker-compose-local.yml up

• API docs (Swagger UI): http://localhost/docs
• Key Manager admin UI: http://localhost:8080

Make a request (cached data → 200 with inline JSON; uncached → 202 + job):

import requests

resp = requests.get(
    "http://localhost/api/v1/hrrr/point/json/",
    headers={"X-API-Key": "your-api-key"},
    params={
        "var": "TMP",              # temperature (Kelvin)
        "timestamp": "2025-07-01T00:00:00",
        "lat": 43.07, "lon": -89.4,
        "epsg": 4326,
    },
)
print(resp.status_code, resp.json())

Pre-populate the cache for a date range (see the caching subsystem doc):

docker exec -d weather_api_interface \
  pixi run python -m weather_api.cache_cli --start 2025-07-01T00 --end 2025-08-01T00

Note: an older version of this README documented an --in-db flag for cache_cli; that flag does not exist. Use --retention-months (or the INDB_RETENTION_MONTHS env var) instead.

---

Repository layout

Path	What it is
weather_api/	The FastAPI service (Python 3.13, Pixi env)
key_manager_ui/	Streamlit admin UI for users/keys (port 8080)
postgis_db/	PostGIS container: raster catalog + US-states geometry
docker-compose.yml	Production compose (behind Traefik)
docker-compose-local.yml	Local dev compose (publishes ports 80 / 8080)
docker-compose-db-only.yml	Just the PostGIS database (port 5432)
docs/	All documentation

Contributing

See docs/developer/contributing.md and docs/developer/local-dev-setup.md. The short version: install Pixi, then from weather_api/:

pixi install
pixi run pre-commit-install   # installs the ruff lint/format git hook
pixi run ok-to-push           # format + lint + test, run before every PR

License

See LICENSE.