Python package
The swatgenx PyPI package: public data functions that need no account, authenticated build requests and downloads 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 — with an account
The example-model catalog and the aggregate summaries need no credential. The wells and the PFAS stations are for verified accounts and the agencies we work with. Request access at swatgenx.com; once we have approved the request, your API key is issued the first time you open dashboard → API keys. Pass it as api_key="..." or set SWATGENX_API_KEY.
import swatgenx as sg # example models in Florida (no key needed) models = sg.catalog(state="FL") # nearest wells + lithology log around a point (API key) sg.groundwater_at(42.73, -84.55, api_key="...") # PFAS monitoring stations in one HUC8 (API key) sg.pfas_stations(huc8="04050006", api_key="...")
| 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, api_key=None) | dict — nearest well record and lithology intervals; needs an API key |
| sg.groundwater_summary() | dict — national groundwater inventory counts |
| sg.pfas_stations(bbox=None, huc12=None, huc8=None, api_key=None) | dict — GeoJSON PFAS monitoring stations; needs an API key |
| sg.pfas_summary() | dict — live PFAS inventory summary |
| sg.access_info() | dict — the access ladder and what each level of access allows |
Requesting builds and downloading — needs an 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() # access level, 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() | The caller’s access level, fair-use allocation, storage in use |
| c.order(usgs_station=None, huc12_outlet=None, force_rebuild=False) | Requests a real build; give a gauge OR a 12-digit HUC12 outlet |
| c.status(order_id) | Build state and stage |
| c.orders() | Every build belonging to the caller |
| c.wait(order_id, poll_seconds=60, timeout_hours=4.0) | Polls until the build 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 access 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)
