Python package
The swatgenx PyPI package: public data functions that need no account, authenticated model ordering and download through Client, and when to use it.
The swatgenx package is a thin, dependency-light client for the same platform this site serves — it talks to the public HTTP API and does no modelling locally. Reach for it when you want a notebook or script to be reproducible: the website is for exploring, the MCP server is for AI agents, and this is for code you re-run.
pip install swatgenx
Public data — free account
Every function in this group works without a credential, but anonymous calls return a small preview with a note. Sign up free at swatgenx.com (Google sign-in works) — your API key is issued automatically the first time you open dashboard → API keys — and the same calls return complete results. Aggregate summaries and the example-model catalog are always complete.
import swatgenx as sg
# calibrated example models in Florida
models = sg.catalog(state="FL", calibrated_only=True)
# recorded calibration for one gauge: NSE, PBIAS, method, window
sg.calibration("01451800")
# nearest wells + lithology log around a point
sg.groundwater_at(42.73, -84.55)
# PFAS monitoring stations in one HUC8
sg.pfas_stations(huc8="04050006")| Function | Returns |
|---|---|
| sg.catalog(state=None, calibrated_only=False, min_channels=None, max_channels=None) | list[dict] — example-model catalog |
| sg.calibration(site_no) | dict | None — cal/val NSE, PBIAS, method; None if never calibrated |
| sg.groundwater_at(lat, lon, tol_deg=0.05) | dict — nearest well record and lithology intervals |
| sg.groundwater_summary() | dict — national groundwater inventory counts |
| sg.pfas_stations(bbox=None, huc12=None, huc8=None) | dict — GeoJSON PFAS monitoring stations |
| sg.pfas_summary() | dict — live PFAS inventory summary |
| sg.access_info() | dict — the access ladder and what each tier unlocks |
Ordering and downloading — needs a free API key
Building a model and downloading one are authenticated actions. Sign in at swatgenx.com, then create a key under dashboard → API keys. Pass it to Client, or set SWATGENX_API_KEY in the environment and let it be picked up.
c = sg.Client(api_key="...") # or env SWATGENX_API_KEY
c.whoami() # tier, quotas, storage used
order = c.order(usgs_station="04124500")
c.wait(order["order_id"]) # blocks, polling until terminal
c.download("04124500", vpuid="0406", dest="model.zip")| Method | Notes |
|---|---|
| c.whoami() | Caller tier, fair-use allocation, storage in use |
| c.order(usgs_station=None, huc12_outlet=None, force_rebuild=False) | Places a real build order; give a gauge OR a 12-digit HUC12 outlet |
| c.status(order_id) | Order state and stage |
| c.orders() | Every order belonging to the caller |
| c.wait(order_id, poll_seconds=60, timeout_hours=4.0) | Polls until the order reaches a terminal state |
| c.download_link(site_no, vpuid, level="usgs_station") | Mints a 24-hour pull URL without downloading |
| c.download(site_no, vpuid, dest, level="usgs_station", timeout=1800) | Fetches the bundle ZIP to dest; returns the path written |
Errors
Every failure raises SwatGenXError, which carries the HTTP status and the server detail alongside the message. Quota and tier rejections arrive this way rather than as a silent empty result, so catch it and read .detail before retrying.
try:
order = c.order(usgs_station="04124500")
except sg.SwatGenXError as e:
print(e.status, e.detail) # e.g. 403 + which limit was hitWhich interface should I use?
- Python package — a script or notebook you want to re-run and share. Explicit, versioned, reproducible.
- MCP server — an AI assistant working on your behalf. Same platform, same limits; the agent calls tools instead of you calling functions. See swatgenx.com/mcp.
- Website — exploring the map, comparing example models, and anything you would rather look at than script.
swatgenx on PyPI · HTTP API reference · MCP server (AI agents)