# dataRetrieval [![CRAN version](http://www.r-pkg.org/badges/version/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) [![](http://cranlogs.r-pkg.org/badges/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) [![](http://cranlogs.r-pkg.org/badges/grand-total/dataRetrieval)](https://cran.r-project.org/package=dataRetrieval) The `dataRetrieval` package was created to simplify the process of loading hydrologic data into the R environment. It is designed to retrieve the major data types of U.S. Geological Survey (USGS) hydrology data that are available on the Web, as well as data from the Water Quality Portal (WQP), which currently houses water quality data from the Environmental Protection Agency (EPA), U.S. Department of Agriculture (USDA), and USGS. # Introduction ⚠️ NWIS web services (readNWIS functions) will be replaced over time by USGS Water Data APIs (read_waterdata\_). Read more about it here: ⚠️ USGS discrete water-quality data availability and format are changing. To view the status of changes in data availability and code functionality, visit: If you have additional questions about these changes, email . # Feedback requested We at USGS Water Data for the Nation want your feedback! Tell us how we’re doing by taking our quick survey: # What would you like to do? 1. Get instantaneous USGS data (for example, discharge sensor data). Start here: [`?read_waterdata_continuous`](reference/read_waterdata_continuous.md). If you only need the latest value, you can use the function: [`?read_waterdata_latest_continuous`](reference/read_waterdata_latest_continuous.md). 2. Get daily USGS data (for example, mean daily discharge). Start here: [`?read_waterdata_daily`](reference/read_waterdata_daily.md). If you only need the latest value, you can use the function: [`?read_waterdata_latest_daily`](reference/read_waterdata_latest_daily.md). 3. Get discrete USGS groundwater data. Start here: [`?read_waterdata_field_measurements`](reference/read_waterdata_field_measurements.md) 4. Get discrete water quality data from a cooperative service that integrates publicly available water-quality data from the USGS, EPA, and over 400 state, federal, tribal, and local agencies. Start here: [`?readWQPdata`](reference/readWQPdata.md) 5. Get USGS discrete water quality data. Start here: [`?read_waterdata_samples`](reference/read_waterdata_samples.md) 6. Get metadata about USGS time series data, including instantaneous and daily data. Start here: [`?read_waterdata_ts_meta`](reference/read_waterdata_ts_meta.md) 7. Find Hydro Network-Linked Data Index (NLDI) data. Start here: [`?findNLDI`](reference/findNLDI.md) 8. Get daily data statistics. Start here: [`?read_waterdata_stats_por`](reference/read_waterdata_stats.md) 9. Add a USGS WaterData API token to your R environment. See: 10. Get the latest status on NWIS, WQP, and other data access updates. See: For additional tutorials, see: [Basic Tutorial](https://doi-usgs.github.io/dataRetrieval/articles/tutorial.html) [dataRetrieval Introduction Slideshow](https://doi-usgs.github.io/dataRetrieval/tutorials/basic_slides_deck.html#/title-slide) # Installation of dataRetrieval To install the `dataRetrieval` package, you must be using R 3.0 or greater and run the following command: ``` r install.packages("dataRetrieval") ``` # New USGS data access The USGS is planning to modernize all web services in the near future. For each of these updates, `dataRetrieval` will create a new function to access the new services. ## API Token You can register an API key for use with USGS water data APIs. There are now limits on how many queries can be requested per IP address per hour. If you find yourself running into limits, you can request an API token here: Then save your token in your .Renviron file like this: ``` R API_USGS_PAT = "my_super_secret_token" ``` You can use `usethis::edit_r_environ()` to edit find and open your .Renviron file. You will need to restart R for that variable to be recognized. ## New Features ### Style New functions will use a “snake case”, such as “read_waterdata_samples”. Older functions use camel case, such as “readNWISdv”. The difference is the underscore between words. This should be a handy way to tell the difference between newer modern data access, and the older traditional functions. ### Structure Historically, we allowed users to customize their queries via the `...` argument structure. With `...`, users needed to know the exact names of query parameters before using the function. Now, the new functions will include **ALL** possible arguments that the web service APIs support. This will allow users to use tab-autocompletes (available in RStudio and other IDEs). **Users will need to understand that it is not advisable to specify all of these parameters. The systems can get bogged down with redundant query parameters.** We expect this will be easier for users, but it might take some time to smooth out the documentation and test usability. There may be additional consequences, such as users won’t be able to build up argument lists to pass into the function. ### Dependencies As we develop functions for the modern USGS Water Data APIs, we’ll continue to explore updating package dependencies. ### Developmental workflow CRAN-stable documentation will be available on the GitHub pages: In-development documentation will be available on the USGS GitLab pages: Development of `dataRetrieval` will happen on a git branch called “develop”. The “develop” branch will only move to the “main” branch when we submit to CRAN, unless there are bug fixes that pertain to the CRAN release. The “develop” branch WILL change frequently, and there are no promises of future behavior. Users must accept that they are using those functions at their own risk. If you willing to accept this risk, the installation instructions are: ``` r library(remotes) install_github("DOI-USGS/dataRetrieval", ref = "develop") ``` # Reporting bugs Please consider reporting bugs and asking questions on the Issues page: # Citations ## Citing the dataRetrieval package ``` r citation(package = "dataRetrieval") #> To cite dataRetrieval in publications, please use: #> #> De Cicco, L.A., Hirsch, R.M., Lorenz, D., Watkins, W.D., Johnson, M., #> Blodgett, D.L., Hinman, E.D., Zemmels, J., 2026, dataRetrieval: R #> packages for discovering and retrieving water data available from #> Federal hydrologic web services, v.2.7.25, doi:10.5066/P9X4L3GE #> #> A BibTeX entry for LaTeX users is #> #> @Manual{, #> author = {Laura DeCicco and Robert Hirsch and David Lorenz and Jordan Read and Jordan Walker and Lindsay Platt and David Watkins and David Blodgett and Mike Johnson and Aliesha Krall and Lee Stanish and Joseph Zemmels and Elise Hinman and Michael Mahoney}, #> title = {dataRetrieval: R packages for discovering and retrieving water data available from U.S. federal hydrologic web services}, #> publisher = {U.S. Geological Survey}, #> address = {Reston, VA}, #> version = {2.7.25}, #> institution = {U.S. Geological Survey}, #> year = {2026}, #> doi = {10.5066/P9X4L3GE}, #> } ``` ## Citing NWIS data U.S. Geological Survey, 2026, USGS Water Data for the Nation: U.S. Geological Survey National Water Information System database, accessed \[April 26, 2026\], at ## Citing WQP data Citations for specific datasets should use this format: National Water Quality Monitoring Council, YYYY, Water Quality Portal, accessed mm, dd, yyyy, hyperlink_for_query, . This can be done using the `create_WQP_bib` function: ``` r SC <- readWQPqw(siteNumbers = "USGS-05288705", parameterCd = "00300") WQPcitation <- create_WQP_bib(SC) WQPcitation #> National Water Quality Monitoring Council (2026). _Water Quality #> Portal_. doi:10.5066/P9QRKUVJ . #> Accessed Sep 09, 2026, #> . print(WQPcitation, style = "Bibtex") #> @Manual{, #> title = {Water Quality Portal}, #> author = {{National Water Quality Monitoring Council}}, #> doi = {10.5066/P9QRKUVJ}, #> note = {Accessed Sep 09, 2026}, #> year = {2026}, #> url = {https://www.waterqualitydata.us/data/Result/search?siteid=USGS-05288705&count=no&pCode=00300&mimeType=csv}, #> } ``` ## Citing Water Quality Portal itself General Water Quality Portal citations should use the following: Water Quality Portal. Washington (DC): National Water Quality Monitoring Council, United States Geological Survey (USGS), Environmental Protection Agency (EPA); 2021. . # Package Support The Water Mission Area of the USGS supports the development and maintenance of `dataRetrieval`, and most likely further into the future. Resources are available primarily for maintenance and responding to user questions. Priorities on the development of new features are determined by the `dataRetrieval` development team. # Disclaimer This software is preliminary or provisional and is subject to revision. It is being provided to meet the need for timely best science. The software has not received final approval by the U.S. Geological Survey (USGS). No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. The software is provided on the condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from the authorized or unauthorized use of the software. # Package index ## USGS Water Data Functions to retrieve USGS Water Data. - [`read_waterdata_samples()`](read_waterdata_samples.md) : USGS Samples Data - [`read_waterdata_stats_por()`](read_waterdata_stats.md) [`read_waterdata_stats_daterange()`](read_waterdata_stats.md) : Get USGS daily data statistics - [`read_waterdata_daily()`](read_waterdata_daily.md) : Get USGS Daily Data - [`read_waterdata_continuous()`](read_waterdata_continuous.md) : Get Continuous USGS Water Data - [`read_waterdata_ts_meta()`](read_waterdata_ts_meta.md) : Get USGS Time Series Metadata - [`read_waterdata_monitoring_location()`](read_waterdata_monitoring_location.md) : Get USGS Monitoring Location Data - [`read_waterdata_latest_continuous()`](read_waterdata_latest_continuous.md) : Get Latest Continuous USGS Water Data - [`read_waterdata_latest_daily()`](read_waterdata_latest_daily.md) : Get Latest USGS Daily Data - [`read_waterdata_latest_field_measurements()`](read_waterdata_latest_field_measurements.md) : Get Latest USGS Field Measurement Data - [`read_waterdata_field_measurements()`](read_waterdata_field_measurements.md) : Get USGS Field Measurement Water Data - [`read_waterdata_parameter_codes()`](read_waterdata_parameter_codes.md) : Get USGS Parameter Code Information - [`read_waterdata_metadata()`](read_waterdata_metadata.md) : Generalized USGS Water Meta Data API retrieval function - [`read_waterdata()`](read_waterdata.md) : Generalized USGS Water Data API retrieval function - [`read_waterdata_channel()`](read_waterdata_channel.md) : Get USGS Channel Measurements - [`read_waterdata_field_meta()`](read_waterdata_field_meta.md) : Get USGS Field Measurement Metadata - [`read_waterdata_combined_meta()`](read_waterdata_combined_meta.md) : Get USGS Monitoring Location Metadata - [`read_waterdata_ratings()`](read_waterdata_ratings.md) : Get USGS Rating Curve Data - [`read_waterdata_peaks()`](read_waterdata_peaks.md) : Get USGS Peak Data - [`summarize_waterdata_samples()`](summarize_waterdata_samples.md) [`summarize_USGS_samples()`](summarize_waterdata_samples.md) : USGS Samples Summary Data - [`check_waterdata_sample_params()`](check_waterdata_sample_params.md) : Check values from codeservice - [`get_monitoring_location_arguments()`](get_monitoring_location_arguments.md) : Get Monitoring Location Arguments ## National Water Information System (NWIS) Functions to retrieve (USGS) NWIS data. These will be slowly phased out and replaced with the read_waterdata family of functions. - [`readNWISdv()`](readNWISdv.md) : Daily Value USGS NWIS Data Retrieval - [`readNWISuv()`](readNWISuv.md) : Instantaneous value data retrieval from USGS (NWIS) - [`readNWISsite()`](readNWISsite.md) : USGS Site File Data Retrieval - [`readNWISstat()`](readNWISstat.md) : Site statistics retrieval from USGS (NWIS) - [`readNWISpCode()`](readNWISpCode.md) : USGS Parameter Data Retrieval - [`readNWISrating()`](readNWISrating.md) : Rating table for an active USGS streamgage retrieval - [`readNWISpeak()`](readNWISpeak.md) : Peak flow data from USGS (NWIS) - [`readNWISuse()`](readNWISuse.md) : Water use data retrieval from USGS (NWIS) - [`readNWISdata()`](readNWISdata.md) : General Data Import from NWIS - [`whatNWISsites()`](whatNWISsites.md) : Site Data Import from NWIS - [`whatNWISdata()`](whatNWISdata.md) : USGS data availability ## Water Quality Portal (WQP) Functions to retrieve WQP data. - [`readWQPqw()`](readWQPqw.md) : Raw Data Import for Water Quality Portal - [`readWQPdata()`](readWQPdata.md) : General Data Import from Water Quality Portal - [`whatWQPsamples()`](wqpSpecials.md) [`whatWQPmetrics()`](wqpSpecials.md) [`whatWQPsites()`](wqpSpecials.md) : Site Data Import from Water Quality Portal - [`whatWQPdata()`](whatWQPdata.md) : Data Available from Water Quality Portal - [`readWQPsummary()`](readWQPsummary.md) : Summary of Data Available from Water Quality Portal - [`wqp_check_status()`](wqp_check_status.md) : Get WQP service metadata ## National Ground-Water Monitoring Network Functions to retrieve NGWMN data. - [`read_ngwmn_water_level()`](read_ngwmn_water_level.md) : Get NGWMN Water Level Data - [`read_ngwmn_sites()`](read_ngwmn_sites.md) : Get NGWMN Site Data - [`read_ngwmn_providers()`](read_ngwmn_providers.md) : Get NGWMN Provider Data - [`read_ngwmn_well_construction()`](read_ngwmn_well_construction.md) : Get NGWMN Well Construction Data - [`read_ngwmn_lithology()`](read_ngwmn_lithology.md) : Get NGWMN Lithology Observations - [`read_ngwmn()`](read_ngwmn.md) : Generalized NGWMN API retrieval function ## Network Linked Data Index Functions to interface with the NLDI. - [`findNLDI()`](findNLDI.md) : R Client for the Network Linked Data Index - [`get_nldi_sources()`](get_nldi_sources.md) : Get current NLDI offerings ## Import data Functions to import different data formats - [`importRDB1()`](importRDB1.md) : Function to return data from the NWIS RDB 1.0 format - [`importNGWMN()`](importNGWMN.md) : Function to return data from the National Ground Water Monitoring Network waterML2 format - [`importWaterML1()`](importWaterML1.md) : Function to return data from the NWISWeb WaterML1.1 service - [`importWaterML2()`](importWaterML2.md) : Parse the WaterML2 timeseries portion of a waterML2 file - [`importWQP()`](importWQP.md) : Basic Water Quality Portal Data parser ## Helper functions - [`create_NWIS_bib()`](create_NWIS_bib.md) : Create NWIS data citation - [`create_WQP_bib()`](create_WQP_bib.md) : Create WQP data citation - [`calcWaterYear()`](calcWaterYear.md) : Extract WY from a date - [`addWaterYear()`](addWaterYear.md) : add a water year column - [`renameNWISColumns()`](renameNWISColumns.md) : renameColumns - [`setAccess()`](setAccess.md) : Set data endpoint - [`countyCdLookup()`](countyCdLookup.md) : US county code look up - [`stateCdLookup()`](stateCdLookup.md) : State code look up - [`countyCd`](countyCd.md) : US County Code Lookup Table - [`parameterCdFile`](parameterCdFile.md) : List of USGS parameter codes - [`stateCd`](stateCd.md) : US State Code Lookup Table - [`zeroPad()`](zeroPad.md) : Pad string with leading zeros - [`dataRetrieval`](dataRetrieval.md) [`dataRetrieval-package`](dataRetrieval.md) : Retrieval functions for USGS and EPA data - [`pcode_to_name()`](pcode_to_name.md) : Parameter code to characteristic name - [`parse_WQP()`](parse_WQP.md) : Convert WQP columns to correct types ## Web query utilities Functions to create web queries - [`constructNWISURL()`](constructNWISURL.md) : Construct NWIS url for data retrieval - [`constructWQPURL()`](constructWQPURL.md) : Construct WQP url for data retrieval - [`getQuerySummary()`](getQuerySummary.md) : getting header information from a WQP query - [`getWebServiceData()`](getWebServiceData.md) : Function to return data from web services - [`is_dataRetrieval_user()`](is_dataRetrieval_user.md) : Is this a dataRetrieval user - [`checkWQPdates()`](checkWQPdates.md) : Date Check for Water Quality Portal - [`get_ogc_params()`](get_ogc_params.md) : Get parameter descriptions # Articles ### All vignettes - [Discover and Download Data](basic_slides.md): - [Updates to dataRetrieval](changes_slides.md): - [Continuous Data](continuous_pr.md): - [How to Contribute](Contributing.md): - [Introducing read_waterdata_statistics\_\*](daily_data_statistics.md): - [Introduction to the dataRetrieval package](dataRetrieval.md): - [Join by closest date](join_by_closest.md): - [Pivot Data](long_to_wide.md): - [Network Linked Data Index: \`dataRetrieval\`](nldi.md): - [Introduction Slides to dataRetrieval](quick_slides.md): - [Changes to NWIS QW services](qwdata_changes.md): - [Introduction to New USGS Water Data APIs](read_waterdata_functions.md): - [USGS Reference Lists](Reference_Lists.md): - [Introducing read_waterdata_samples](samples_data.md): - [dataRetrieval Status](Status.md): - [dataRetrieval Tutorial](tutorial.md): - [Large Data Pulls from Water Quality Portal - A Script-Based Approach](wqp_large_pull_script.md): - [Large Data Pulls from Water Quality Portal - A Pipeline-Based Approach](wqp_large_pull_targets.md): - [Changes to dataRetrieval for delivering discrete sample data](wqx3_development_plan.md):