gagely 0.1.0

Tools for retrieving US weather, streamflow, and rainfall gage data from services such as Contrail and USGS.

gagely

gagely provides Python utilities for retrieving US weather, streamflow, rainfall, and related gage data from services such as Contrail and USGS, with helpers for writing time-series data to HEC-DSS through pydsstools.

The Python import package is named gagely.

Installation

Install from a local checkout:

python -m pip install .

For development:

python -m pip install -e ".[dev]"

Versioning

Package versions are derived from git tags with setuptools-scm.

Use tags such as:

git tag 0.1.0

Then build/install from that tagged checkout.

Basic Usage

USGS

The USGS package wraps dataretrieval.waterdata and adds DSS-write helpers. Set the personal access token once per process, then go through the daily or continuous submodule:

from gagely.usgs import configure_usgs, daily, continuous

configure_usgs("YOUR_USGS_API_KEY")

Daily values to DSS (period-mean, written as a regular 1DAY series — each row is shifted to the period-end timestamp DSS expects):

daily.flow_to_dss(
    output="flow.dss",
    site_id="08354900",
    sdate="2000-01-01",
)

Continuous (instantaneous) values to DSS (sampling interval is inferred per site from the data, e.g. 15MIN for a typical 15-minute gage; internal time gaps are filled with the no-data sentinel UNDEFINED):

continuous.to_dss(
    output="iv.dss",
    site_id="12362500",
    param="flow",
    sdate="2026-01-01",
)

Returning a DataFrame instead of writing to DSS:

df_daily = daily.get_flow("08354900", sdate="2020-01-01")
df_iv    = continuous.get_flow("12362500", sdate="2026-01-01")

site_id accepts a single id, a list, or a dict mapping label → id (the dict keys become the DSS APART). Bare USGS ids ("08354900") and prefixed ones ("USGS-08354900") are both accepted.

Each submodule exposes the same helper set: get_flow, get_stage, to_dss, flow_to_dss, stage_to_dss, plus the canonical endpoint-name function (get_daily or get_continuous) for arbitrary parameter / statistic combinations. The endpoint-name functions are also re-exported at the package level: from gagely.usgs import get_daily, get_continuous.

Contrail

from gagely.contrail import configure_contrail, fetch_to_dss

configure_contrail(url="https://contrail.example.com", system_key="YOUR_KEY")
fetch_to_dss(
    output="rainfall.dss",
    sensor_class=10,
    sdate="2000-01-01",
    or_site_id=200,
)

Resolve gage names to Contrail or_site_id values before fetching:

from gagely.contrail import get_site_metadata, validate_gages

site_meta = get_site_metadata()
gage_to_or_id = validate_gages(
    ["Station 2", "City Hall"],
    site_meta,
)

Site and sensor metadata can also be queried directly, filtered by site_id or or_site_id (and, for sensors, sensor_class):

from gagely.contrail import get_site_metadata, get_sensor_metadata

# Omit site_id / or_site_id to get metadata for every site/sensor
# accessible under the configured URL/system key.
site_meta = get_site_metadata(or_site_id="200")
sensor_meta = get_sensor_metadata(or_site_id="200", sensor_class=10)

Both return a list of dicts, one per <row> in the XML response (each dict maps child-element tag → text).

Contributing

Bug reports, feature requests, and pull requests are welcome — see CONTRIBUTING.md for guidelines. This project follows the Code of Conduct.

License

gagely is licensed under the MIT License.