Metadata-Version: 2.1
Name: hydrotools.nwis_client
Version: 3.4.1
Summary: A convenient interface to the USGS NWIS Instantaneous Values (IV) REST Service API.
Author-email: Austin Raney <aaraney@protonmail.com>, "Jason A. Regina" <jason.regina@noaa.gov>
License: “Software code created by U.S. Government employees is not subject to copyright
        in the United States (17 U.S.C. §105). The United States/Department of Commerce
        reserve all rights to seek and obtain copyright protection in countries other
        than the United States for Software authored in its entirety by the Department
        of Commerce. To this end, the Department of Commerce hereby grants to Recipient
        a royalty-free, nonexclusive license to use, copy, and create derivative works
        of the Software outside of the United States.”
        
Project-URL: Homepage, https://github.com/NOAA-OWP/hydrotools
Project-URL: Documentation, https://noaa-owp.github.io/hydrotools/hydrotools.nwis_client.html
Project-URL: Repository, https://github.com/NOAA-OWP/hydrotools/tree/main/python/nwis_client
Project-URL: Bug Tracker, https://github.com/NOAA-OWP/hydrotools/issues
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: Free To Use But Restricted
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Hydrology
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: numpy
Requires-Dist: hydrotools._restclient>=3.0.4
Requires-Dist: aiohttp
Requires-Dist: click
Provides-Extra: develop
Requires-Dist: pytest; extra == "develop"
Requires-Dist: pytest-aiohttp; extra == "develop"

# OWPHydroTools :: NWIS Client

This subpackage implements an interface to the USGS NWIS [Instantaneous Values Web Service](https://waterservices.usgs.gov/rest/IV-Service.html). The primary use for this tool is to populate `pandas.Dataframe` objects with USGS streamflow data. See the [NWIS Client Documentation](https://noaa-owp.github.io/hydrotools/hydrotools.nwis_client.html) for a complete list and description of the currently available methods. To report bugs or request new features, submit an issue through the [OWPHydroTools Issue Tracker](https://github.com/NOAA-OWP/hydrotools/issues) on GitHub.

## Installation

In accordance with the python community, we support and advise the usage of virtual
environments in any workflow using python. In the following installation guide, we
use python's built-in `venv` module to create a virtual environment in which the
tool will be installed. Note this is just personal preference, any python virtual
environment manager should work just fine (`conda`, `pipenv`, etc. ).

```bash
# Create and activate python environment, requires python >= 3.8
$ python3 -m venv venv
$ source venv/bin/activate
$ python3 -m pip install --upgrade pip

# Install nwis_client
$ python3 -m pip install hydrotools.nwis_client
```

## Usage

The following example demonstrates how one might use `hydrotools.nwis_client` to retrieve USGS streamflow observations.

### Code

```python
# Import the NWIS IV Client
from hydrotools.nwis_client.iv import IVDataService

# Retrieve data from a single site
service = IVDataService(
    value_time_label="value_time"
)
observations_data = service.get(
    sites='01646500',
    startDT='2019-08-01',
    endDT='2020-08-01'
    )

# Look at the data
print(observations_data.head())
```

### Output

```console
           value_date variable_name usgs_site_code measurement_unit   value qualifiers  series
0 2019-08-01 04:00:00    streamflow       01646500            ft3/s  4170.0        [A]       0
1 2019-08-01 04:15:00    streamflow       01646500            ft3/s  4170.0        [A]       0
2 2019-08-01 04:30:00    streamflow       01646500            ft3/s  4170.0        [A]       0
3 2019-08-01 04:45:00    streamflow       01646500            ft3/s  4170.0        [A]       0
4 2019-08-01 05:00:00    streamflow       01646500            ft3/s  4170.0        [A]       0
```

### Command Line Interface (CLI)
The `hydrotools.nwis_client` package includes a command-line utility.

This example demonstrates calling the help page:
```bash
$ nwis-client --help
```
```console
Usage: nwis-client [OPTIONS] [SITES]...

  Retrieve data from the USGS IV Web Service API and write in CSV format.

  Example:

  nwis-client 01013500 02146470

Options:
  -o, --output FILENAME       Output file path
  -s, --startDT TIMESTAMP     Start datetime
  -e, --endDT TIMESTAMP       End datetime
  -p, --parameterCd TEXT      Parameter code
  --comments / --no-comments  Enable/disable comments in output, enabled by
                              default
  --header / --no-header      Enable/disable header in output, enabled by
                              default
  --help                      Show this message and exit.
```

This example retrieves the last discharge value from two sites:
```bash
$ nwis-client 01013500 02146470
```
```console
# USGS IV Service Data
# 
# value_date: Datetime of measurement (UTC) (character string)
# variable: USGS variable name (character string)
# usgs_site_code: USGS Gage Site Code (character string)
# measurement_unit: Units of measurement (character string)
# value: Measurement value (float)
# qualifiers: Qualifier string (character string)
# series: Series number in case multiple time series are returned (integer)
# 
# Generated at 2022-03-04 21:56:30.296051+00:00
# nwis_client version: 3.2.0
# Source code: https://github.com/NOAA-OWP/hydrotools
# 
value_time,variable_name,usgs_site_code,measurement_unit,value,qualifiers,series
2022-03-04 21:45:00,streamflow,01013500,ft3/s,-999999.00,"['P', 'Ice']",0
2022-03-04 21:50:00,streamflow,02146470,ft3/s,1.04,['P'],0
```

This example retrieves stage data from two sites for a specific time period:
```bash
$ nwis-client -p 00065 -s 2021-06-01T00:00 -e 2021-06-01T01:00 01013500 02146470
```
```console
# USGS IV Service Data
# 
# value_date: Datetime of measurement (UTC) (character string)
# variable: USGS variable name (character string)
# usgs_site_code: USGS Gage Site Code (character string)
# measurement_unit: Units of measurement (character string)
# value: Measurement value (float)
# qualifiers: Qualifier string (character string)
# series: Series number in case multiple time series are returned (integer)
# 
# Generated at 2022-03-04 21:59:02.508468+00:00
# nwis_client version: 3.2.0
# Source code: https://github.com/NOAA-OWP/hydrotools
# 
value_time,variable_name,usgs_site_code,measurement_unit,value,qualifiers,series
2021-05-31 23:00:00,gage height,01013500,ft,4.28,['A'],0
2021-05-31 23:15:00,gage height,01013500,ft,4.28,['A'],0
2021-05-31 23:30:00,gage height,01013500,ft,4.28,['A'],0
2021-05-31 23:45:00,gage height,01013500,ft,4.28,['A'],0
2021-06-01 00:00:00,gage height,01013500,ft,4.28,['A'],0
2021-05-31 23:00:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:05:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:10:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:15:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:20:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:25:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:30:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:35:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:40:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:45:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:50:00,gage height,02146470,ft,3.14,['A'],0
2021-05-31 23:55:00,gage height,02146470,ft,3.14,['A'],0
2021-06-01 00:00:00,gage height,02146470,ft,3.14,['A'],0
```
