SWATGenXSWATGenX
ResearchDocs
Open Explorer Work with us
SWATGenXDocs

Python package

Applies to SWATGenX engine extensions · Updated August 2026

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
Signatures below are from the released package (0.1.1). Its only dependency is requests, and it needs Python 3.9 or newer.

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="...")
FunctionReturns
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
Without a key, groundwater_at and pfas_stations raise SwatGenXError (401, needs an API key); with a key whose account lacks that access, the site answers 403 and the error carries its sentence.
USGS site numbers keep their leading zero ("01451800"). Passing one through int() or a spreadsheet cell silently drops it and turns a valid gauge into a lookup miss — keep them as strings.

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")
MethodNotes
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
Build time scales with watershed size — typically 20 minutes to 2 hours. c.wait defaults to a 4-hour ceiling and polls once a minute; for a large basin prefer c.status in your own loop over holding a process open.

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 hit

Which 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)