Skip to content

Enrich waterdata getter docstrings with examples adapted from R #265

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
thodson-usgs merged 2 commits into from
May 6, 2026
+64 −7
Merged

Enrich waterdata getter docstrings with examples adapted from R #265

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a82f2a
Enrich waterdata getter docstrings with examples adapted from R
thodson-usgs May 5, 2026
b2b87fd
Fix continuation in get_field_measurements multi-site example
thodson-usgs May 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 64 additions & 7 deletions dataretrieval/waterdata/api.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,11 +208,27 @@ def get_daily(
... time="2021-01-01T00:00:00Z/2022-01-01T00:00:00Z",
... )

>>> # Quick "show me the last week" idiom (ISO 8601 duration)
>>> df, md = dataretrieval.waterdata.get_daily(
... monitoring_location_id="USGS-02238500",
... parameter_code="00060",
... time="P7D",
... )

>>> # Get approved daily flow data from multiple sites
>>> df, md = dataretrieval.waterdata.get_daily(
... monitoring_location_id = ["USGS-05114000", "USGS-09423350"],
... approval_status = "Approved",
... time = "2024-01-01/.."
... monitoring_location_id=["USGS-05114000", "USGS-09423350"],
... approval_status="Approved",
... time="2024-01-01/..",
... )

>>> # Pull only rows whose underlying record was refreshed in the
>>> # last 7 days — handy for incremental ETL polling
>>> df, md = dataretrieval.waterdata.get_daily(
... monitoring_location_id="USGS-02238500",
... parameter_code="00060",
... last_modified="P7D",
... )
"""
service = "daily"
output_id = "daily_id"
Expand Down Expand Up @@ -1097,6 +1113,22 @@ def get_latest_continuous(
... monitoring_location_id="USGS-02238500", parameter_code="00060"
... )

>>> # Restrict to the last 7 days; sites with no observation in that
>>> # window are dropped instead of returned with stale values
>>> df, md = dataretrieval.waterdata.get_latest_continuous(
... monitoring_location_id="USGS-02238500",
... parameter_code="00060",
... time="P7D",
... )

>>> # Pull only rows whose underlying record was refreshed in the
>>> # last 7 days, across multiple sites and parameters
>>> df, md = dataretrieval.waterdata.get_latest_continuous(
... monitoring_location_id=["USGS-451605097071701", "USGS-14181500"],
... parameter_code=["00060", "72019"],
... last_modified="P7D",
... )

>>> # Get latest continuous measurements for multiple sites
>>> df, md = dataretrieval.waterdata.get_latest_continuous(
... monitoring_location_id=["USGS-05114000", "USGS-09423350"]
Expand Down Expand Up @@ -1278,6 +1310,21 @@ def get_latest_daily(
... monitoring_location_id="USGS-02238500", parameter_code="00060"
... )

>>> # Restrict to rows whose underlying record was refreshed in the
>>> # last 7 days
>>> df, md = dataretrieval.waterdata.get_latest_daily(
... monitoring_location_id="USGS-02238500",
... parameter_code="00060",
... last_modified="P7D",
... )

>>> # Multi-site, multi-parameter — discharge and water temperature
>>> # at two sites in a single round-trip
>>> df, md = dataretrieval.waterdata.get_latest_daily(
... monitoring_location_id=["USGS-01491000", "USGS-01645000"],
... parameter_code=["00060", "00010"],
... )

>>> # Get most recent daily measurements for two sites
>>> df, md = dataretrieval.waterdata.get_latest_daily(
... monitoring_location_id=["USGS-05114000", "USGS-09423350"]
Expand Down Expand Up @@ -1454,13 +1501,23 @@ def get_field_measurements(
... skip_geometry=True,
... )

>>> # Half-bounded time range: every measurement at this site since
>>> # 1980 (open-ended end). Use ``"../<date>"`` for the inverse
>>> # (everything up to a date).
>>> df, md = dataretrieval.waterdata.get_field_measurements(
... monitoring_location_id="USGS-425957088141001",
... time="1980-01-01/..",
... )

>>> # Get field measurements from multiple sites and
>>> # parameter codes from the last 20 years
>>> df, md = dataretrieval.waterdata.get_field_measurements(
... monitoring_location_id = ["USGS-451605097071701",
"USGS-263819081585801"],
... parameter_code = ["62611", "72019"],
... time = "P20Y"
... monitoring_location_id=[
... "USGS-451605097071701",
... "USGS-263819081585801",
... ],
... parameter_code=["62611", "72019"],
... time="P20Y",
... )
"""
service = "field-measurements"
Expand Down
Loading