diff --git a/README.md b/README.md index d651be6c..bf3a319d 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,30 @@ import logging logging.basicConfig(level=logging.DEBUG) ``` +### National Ground-Water Monitoring Network (NGWMN) + +Access groundwater data aggregated from many state, federal, and local +agencies. NGWMN uses the same OGC engine as the Water Data API, +so chunking and pagination behave the same way: + +```python +from dataretrieval import ngwmn + +# Find the groundwater monitoring sites in a state +# (state accepts a full name, a postal code like 'WI', or a FIPS code like '55') +sites, metadata = ngwmn.get_sites(state='Wisconsin') + +print(f"Found {len(sites)} NGWMN sites in Wisconsin") + +# Pull water levels from the first twenty sites over a time window. +water_levels, metadata = ngwmn.get_water_level( + monitoring_location_id=sites['monitoring_location_id'][:20], + datetime=['2022-01-01', '2024-01-01'] +) + +print(f"Retrieved {len(water_levels)} water-level observations") +``` + ### Water Quality Portal (WQP) Access water quality data from multiple agencies: @@ -170,35 +194,43 @@ print(f"Found {len(flowlines)} upstream tributaries within 50km") ## Available Data Services -### Modern USGS Water Data APIs (Recommended) -- **Daily values**: Daily statistical summaries (mean, min, max) -- **Instantaneous values**: High-frequency continuous data -- **Field measurements**: Discrete measurements from field visits -- **Monitoring locations**: Site information and metadata -- **Time series metadata**: Information about available data parameters -- **Latest daily values**: Most recent daily statistical summary data -- **Latest instantaneous values**: Most recent high-frequency continuous data -- **Daily, monthly, and annual statistics**: Median, maximum, minimum, arithmetic mean, and percentile statistics -- **Samples data**: Discrete USGS water quality data - -### Legacy NWIS Services (Deprecated) -- **Daily values (dv)**: Legacy daily statistical data -- **Instantaneous values (iv)**: Legacy continuous data -- **Site info (site)**: Basic site information -- **Statistics (stat)**: Statistical summaries -- **Discharge peaks (peaks)**: Annual peak discharge events - -### Water Quality Portal -- **Results**: Water quality analytical results from USGS, EPA, and other agencies -- **Sites**: Monitoring location information -- **Organizations**: Data provider information -- **Projects**: Sampling project details - -### Network Linked Data Index (NLDI) -- **Basin delineation**: Watershed boundaries for any point -- **Flow navigation**: Upstream/downstream network traversal -- **Feature discovery**: Find monitoring sites, dams, and other features -- **Hydrologic connectivity**: Link data across the stream network +### Modern USGS Water Data APIs (Recommended) — `dataretrieval.waterdata` +- `get_daily`: Daily statistical summaries (mean, min, max) +- `get_continuous`: High-frequency continuous (instantaneous) values +- `get_field_measurements`: Discrete measurements from field visits +- `get_monitoring_locations`: Site information and metadata +- `get_time_series_metadata`: A location's available data parameters +- `get_latest_daily`: Most recent daily statistical summary +- `get_latest_continuous`: Most recent high-frequency value +- `get_stats_por` / `get_stats_date_range`: Daily, monthly, and annual statistics +- `get_samples`: Discrete USGS water-quality samples +- `get_ratings`: Stage-discharge rating curves + +### National Ground-Water Monitoring Network (NGWMN) — `dataretrieval.ngwmn` +- `get_sites`: Groundwater monitoring-location metadata across many agencies +- `get_water_level`: Depth-to-water and water-level observations +- `get_lithology`: Geologic-material logs by depth interval +- `get_well_construction`: Casing, screen, and build-out records +- `get_providers`: Contributing data-provider organizations + +### Legacy NWIS Services (Deprecated) — `dataretrieval.nwis` +- `get_dv`: Legacy daily statistical data +- `get_iv`: Legacy continuous (instantaneous) data +- `get_info`: Basic site information +- `get_stats`: Statistical summaries +- `get_discharge_peaks`: Annual peak discharge events + +### Water Quality Portal — `dataretrieval.wqp` +- `get_results`: Water-quality analytical results from USGS, EPA, and other agencies +- `what_sites`: Monitoring-location information +- `what_organizations`: Data-provider information +- `what_projects`: Sampling-project details + +### Network Linked Data Index (NLDI) — `dataretrieval.nldi` +- `get_basin`: Watershed boundary for a point or feature +- `get_flowlines`: Upstream/downstream flowline navigation +- `get_features`: Find monitoring sites, dams, and other features along the network +- `get_features_by_data_source`: Features from a specific data source ## More Examples diff --git a/dataretrieval/waterdata/api.py b/dataretrieval/waterdata/api.py index b2092d62..8d686f74 100644 --- a/dataretrieval/waterdata/api.py +++ b/dataretrieval/waterdata/api.py @@ -65,7 +65,7 @@ def get_daily( unit_of_measure: str | Iterable[str] | None = None, qualifier: str | Iterable[str] | None = None, value: str | Iterable[str] | None = None, - last_modified: str | None = None, + last_modified: str | Iterable[str] | None = None, skip_geometry: bool | None = None, time: str | Iterable[str] | None = None, bbox: list[float] | None = None, @@ -288,7 +288,7 @@ def get_continuous( unit_of_measure: str | Iterable[str] | None = None, qualifier: str | Iterable[str] | None = None, value: str | Iterable[str] | None = None, - last_modified: str | None = None, + last_modified: str | Iterable[str] | None = None, time: str | Iterable[str] | None = None, limit: int | None = None, filter: str | None = None, diff --git a/docs/source/conf.py b/docs/source/conf.py index 9d478f98..b129d35b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -39,8 +39,8 @@ # suffix of source documents source_suffix = ".rst" -# The main toctree document. -main_doc = "index" +# The root toctree document. +root_doc = "index" # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the diff --git a/docs/source/examples/peak_streamflow_trends.nblink b/docs/source/examples/peak_streamflow_trends.nblink index 1bf99495..b707fea1 100644 --- a/docs/source/examples/peak_streamflow_trends.nblink +++ b/docs/source/examples/peak_streamflow_trends.nblink @@ -1,6 +1,3 @@ { - "path": "../../../demos/peak_streamflow_trends.ipynb", - "extra-media": [ - "../../../demos/datasets" - ] + "path": "../../../demos/peak_streamflow_trends.ipynb" } diff --git a/docs/source/reference/index.rst b/docs/source/reference/index.rst index 48947ff8..23608ce1 100644 --- a/docs/source/reference/index.rst +++ b/docs/source/reference/index.rst @@ -12,6 +12,7 @@ API reference ngwmn nldi nwis + samples streamstats utils waterdata diff --git a/docs/source/reference/samples.rst b/docs/source/reference/samples.rst new file mode 100644 index 00000000..902dd297 --- /dev/null +++ b/docs/source/reference/samples.rst @@ -0,0 +1,8 @@ +.. _samples: + +dataretrieval.samples +--------------------- + +.. automodule:: dataretrieval.samples + :members: + :special-members: