Package: hydrotools.nwis-client
OWPHydroTools :: NWIS ClientThis subpackage implements an interface to the USGS NWISInstantaneous Values Web Service. The primary use for this tool is to populatepandas.Dataframeobjects with USGS streamflow data. See theNWIS Client Documentationfor a complete list and description of the currently available methods. To report bugs or request new features, submit an issue through theOWPHydroTools Issue Trackeron GitHub.InstallationIn 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-invenvmodule 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. ).# Create and activate python environment, requires python >= 3.8$python3-mvenvvenv
$sourcevenv/bin/activate
$python3-mpipinstall--upgradepip# Install nwis_client$python3-mpipinstallhydrotools.nwis_clientUsageThe following example demonstrates how one might usehydrotools.nwis_clientto retrieve USGS streamflow observations.Code# Import the NWIS IV Clientfromhydrotools.nwis_client.ivimportIVDataService# Retrieve data from a single siteservice=IVDataService(value_time_label="value_time")observations_data=service.get(sites='01646500',startDT='2019-08-01',endDT='2020-08-01')# Look at the dataprint(observations_data.head())Outputvalue_date variable_name usgs_site_code measurement_unit   value qualifiers  series0 2019-08-01 04:00:00    streamflow       01646500            ft3/s  4170.0        [A]       01 2019-08-01 04:15:00    streamflow       01646500            ft3/s  4170.0        [A]       02 2019-08-01 04:30:00    streamflow       01646500            ft3/s  4170.0        [A]       03 2019-08-01 04:45:00    streamflow       01646500            ft3/s  4170.0        [A]       04 2019-08-01 05:00:00    streamflow       01646500            ft3/s  4170.0        [A]       0Command Line Interface (CLI)Thehydrotools.nwis_clientpackage includes a command-line utility.This example demonstrates calling the help page:$nwis-client--helpUsage: nwis-client [OPTIONS] [SITES]...Retrieve data from the USGS IV Web Service API and write in CSV format.Example:nwis-client 01013500 02146470Options:-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 bydefault--header / --no-header      Enable/disable header in output, enabled bydefault--help                      Show this message and exit.This example retrieves the last discharge value from two sites:$nwis-client0101350002146470#USGSIVServiceData##value_date:Datetimeofmeasurement(UTC)(characterstring)#variable:USGSvariablename(characterstring)#usgs_site_code:USGSGageSiteCode(characterstring)#measurement_unit:Unitsofmeasurement(characterstring)#value:Measurementvalue(float)#qualifiers:Qualifierstring(characterstring)#series:Seriesnumberincasemultipletimeseriesarereturned(integer)##Generatedat2022-03-0421:56:30.296051+00:00#nwis_clientversion:3.2.0#Sourcecode:https://github.com/NOAA-OWP/hydrotools#value_time,variable_name,usgs_site_code,measurement_unit,value,qualifiers,series2022-03-04 21:45:00,streamflow,01013500,ft3/s,-999999.00,"['P', 'Ice']",02022-03-04 21:50:00,streamflow,02146470,ft3/s,1.04,['P'],0This example retrieves stage data from two sites for a specific time period:$nwis-client-p00065-s2021-06-01T00:00-e2021-06-01T01:000101350002146470#USGSIVServiceData##value_date:Datetimeofmeasurement(UTC)(characterstring)#variable:USGSvariablename(characterstring)#usgs_site_code:USGSGageSiteCode(characterstring)#measurement_unit:Unitsofmeasurement(characterstring)#value:Measurementvalue(float)#qualifiers:Qualifierstring(characterstring)#series:Seriesnumberincasemultipletimeseriesarereturned(integer)##Generatedat2022-03-0421:59:02.508468+00:00#nwis_clientversion:3.2.0#Sourcecode:https://github.com/NOAA-OWP/hydrotools#value_time,variable_name,usgs_site_code,measurement_unit,value,qualifiers,series2021-05-31 23:00:00,gage height,01013500,ft,4.28,['A'],02021-05-31 23:15:00,gage height,01013500,ft,4.28,['A'],02021-05-31 23:30:00,gage height,01013500,ft,4.28,['A'],02021-05-31 23:45:00,gage height,01013500,ft,4.28,['A'],02021-06-01 00:00:00,gage height,01013500,ft,4.28,['A'],02021-05-31 23:00:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:05:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:10:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:15:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:20:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:25:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:30:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:35:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:40:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:45:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:50:00,gage height,02146470,ft,3.14,['A'],02021-05-31 23:55:00,gage height,02146470,ft,3.14,['A'],02021-06-01 00:00:00,gage height,02146470,ft,3.14,['A'],0