Checking for non-preferred file/folder path names (may take a long time depending on the number of files/folders) ...

USGS dataretrieval Python Package Usage Examples

Owners: This resource does not have an owner who is an active HydroShare user. Contact CUAHSI ( for information on this resource.
Type: Resource
Storage: The size of this resource is 100.3 KB
Created: Aug 31, 2021 at 4:21 a.m.
Last updated: Sep 16, 2022 at 9:18 p.m.
Citation: See how to cite this resource
Sharing Status: Public
Views: 3676
Downloads: 1211
+1 Votes: Be the first one to 
Comments: No comments (yet)


This resource contains a set of Jupyter Notebooks that provide Python code examples for using the Python dataretrieval package for retrieving data from the United States Geological Survey's (USGS) National Water Information System (NWIS).The dataretrieval package is a Python alternative to USGS-R's dataRetrieval package for the R Statistical Computing Environment used for obtaining USGS or Environmental Protection Agency (EPA) water quality data, streamflow data, and metadata directly from web services. The dataretrieval Python package is an alternative to the R package, not a port, in that it reproduces the functionality of the R package but its organization and functionality differ to some degree. The dataretrieval package was originally created by Timothy Hodson at USGS. Additional contributions to the Python package and these Jupyter Notebook examples were created at Utah State University under funding from the National Science Foundation. A link to the GitHub source code repository for the dataretrieval package is provided in the related resources section below.

Subject Keywords



This resource contains Jupyter Notebooks that serve as examples of how to use the USGS dataretrieval Python package to retrieve data from the United States Geological Survey's National Water Information System. These notebooks can either be downloaded and run in your local environment, or they can be launched into the CUAHSI JupyterHub server. The following notebooks are provided:

  • USGS_dataretrieval_DailyValues_Examples.ipynb: This notebook demonstrates how to use the get_dv() function to retrieve daily values (e.g., daily streamflow values) for USGS monitoring sites.
  • USGS_dataretrieval_GroundwaterLevels_Examples.ipynb: This notebook demonstrates how to use the get_gwlevels() function to retrieve groundwater level data for USGS monitoring sites.
  • USGS_dataretrieval_Measurements_Examples.ipynb: This notebook demonstrates how to use the get_discharge_measurements() function to retrieve surface water discharge measurements for USGS monitoring sites.
  • USGS_dataretrieval_ParameterCodes_examples.ipynb: This notebook demonstrates how to use the get_pmcodes() function to retrieve information about USGS NWIS parameter codes.
  • USGS_dataretrieval_Peaks_examples.ipynb: This notebook demonstrates how to use the get_discharge_peaks() function to retrieve peack discharge data for USGS NWIS monitoring sites.
  • USGS_dataretrieval_Ratings_Examples.ipynb: This notebook demonstrates how to use the get_ratings() function to retrieve rating curve data for USGS monitoring sites.
  • USGS_dataretrieval_SiteInfo_Examples.ipynb: This notebook demonstrates how to use the get_info() function to retrieve information about a USGS monitoring site.
  • USGS_dataretrieval_SiteInventory_Examples.ipynb: This notebook demonstrates how to use the what_sites() function to search NWIS for sites within a region with specific data.
  • USGS_dataretrieval_Statistics_Examples.ipynb: This notebook demonstrate how to use the get_stats() function to retrieve site statistics for USGS monitoring sites.
  • USGS_dataretrieval_UnitValues_Examples.ipynb: This notebook demonstrates how to use the get_iv() function to retrieve instantaneous (unit) value data for USGS monitoring sites.
  • USGS_dataretrieval_WaterSamples_Examples.ipynb: This notebook demonstrates how to use the get_qwdata() function to retrieve water quality sample data for USGS monitoring sites.
  • USGS_dataretrieval_WaterUse_Examples.ipynb: This notebook demonstrates how to use the get_water_use() function to retrieve water use data.

Run these Notebooks Locally

If you want to run these notebooks locally on your machine, you will need to be set up to run Jupyter notebooks. If you need help setting up Jupyter to run notebooks, you can consult the Jupyter/IPython Notebook Quick Start Guide.

There are also Python Interactive Development Environments (IDEs) like PyCharm that have support for creating, editing, and running Jupyter Notebooks.

Run these Notebooks on the CUAHSI JupyterHub Server

CUAHSI maintains a HydroShare linked JupyterHub server on which you can run these notebook. To run these notebooks using CUAHSI's JupyterHub Server, do the following:

  1. Click on the "Open with" button at the top of this resource's landing page and select "CUAHSI JupyterHub."
  2. If prompted, agree to the terms of use and click the "Sign in with HydroShare" button. You will need to click the "Authorize" button to authorize CUAHSI JupyterHub to interact with your HydroShare account.
  3. Once your content has been copied to the CUAHSI JupyterHub server, click on the name of the notebook you want to execute.
  4. This will launch the Jupyter Notebook and you can execute it using the controls at the top of the notebook.

Related Resources

This resource is described by GitHub repository for the USGS Python dataretrieval package:


Funding Agencies

This resource was created using funding from the following sources:
Agency Name Award Title Award Number
United States Geological Survey
National Science Foundation Collaborative Research: Elements: Advancing Data Science and Analytics for Water (DSAW) 1931297

How to Cite

Horsburgh, J. S., A. S. Jones, S. S. Black, T. O. Hodson (2022). USGS dataretrieval Python Package Usage Examples, HydroShare,

This resource is shared under the Creative Commons Attribution CC BY.


There are currently no comments

New Comment