Requesting Site Information

The USGS provides a site file for every stream gauge in its network. This file contains information about the location where the data are collected and about the watershed. You can request this information using the hydrofunctions site_file() function. This will return a hydroRDB object, which contains a table (dataframe) with a row for every site that you request, and a header that describes every column in the dataset.

Some of the most useful information provided by the site file includes:

• latitude, longitude, altitude, & datum

• location data including state, county, and Hydrologic Unit Codes (HUC)

• accuracy codes

• additional codes describing the topographic setting and aquifer

• watershed area & landcover

• well data (if a well is present): depth & aquifer code

For more information about a site and the data collected at the site, try these sources:

• To access information about the data collected at a site, use the data_catalog() function.

• To access the rating curve at a site (for translating water stage into discharge), use the rating_curve() function.

• To access field data collected by USGS personnel during site visits, use the field_meas() function.

• To access the annual peak discharges at a site, use the peaks() function.

• To access daily, monthly, or annual statistics for data at a site, use the stats() function.

import hydrofunctions as hf

output = hf.site_file('01585200')

Retrieved the site file for site #01585200 from https://waterservices.usgs.gov/nwis/site/?format=rdb&sites=01585200&siteOutput=expanded&siteStatus=all

Our new ‘output’ is a hydroRDB object. It has several useful properties, including:

• .table, which returns a dataframe of the data. Each row corresponds to a different site.

• .header, which is the original descriptive header provided by the USGS. It lists and describes the variables in the dataset.

• .columns, which is a list of the column names

• .dtypes, which is a list of the data types and column widths for each variable in the USGS RDB format.

If you print or evaluate the hydroRDB object, it will return a tuple of the header and dataframe table, like this:

output

hydroRDB(header=

#
#
# US Geological Survey
# retrieved: 2021-08-09 22:28:38 -04:00 (vaas01)
#
# The Site File stores location and general information about groundwater,
# surface water, and meteorological sites
# for sites in USA.
#
# File-format description: http://help.waterdata.usgs.gov/faq/about-tab-delimited-output
# Automated-retrieval info: http://waterservices.usgs.gov/rest/Site-Service.html
#
# Contact: gs-w_support_nwisweb@usgs.gov
#
# The following selected fields are included in this output:
#
# agency_cd -- Agency
# site_no -- Site identification number
# station_nm -- Site name
# site_tp_cd -- Site type
# lat_va -- DMS latitude
# long_va -- DMS longitude
# dec_lat_va -- Decimal latitude
# dec_long_va -- Decimal longitude
# coord_meth_cd -- Latitude-longitude method
# coord_acy_cd -- Latitude-longitude accuracy
# coord_datum_cd -- Latitude-longitude datum
# dec_coord_datum_cd -- Decimal Latitude-longitude datum
# district_cd -- District code
# state_cd -- State code
# county_cd -- County code
# country_cd -- Country code
# land_net_ds -- Land net location description
# map_nm -- Name of location map
# map_scale_fc -- Scale of location map
# alt_va -- Altitude of Gage/land surface
# alt_meth_cd -- Method altitude determined
# alt_acy_va -- Altitude accuracy
# alt_datum_cd -- Altitude datum
# huc_cd -- Hydrologic unit code
# basin_cd -- Drainage basin code
# topo_cd -- Topographic setting code
# instruments_cd -- Flags for instruments at site
# construction_dt -- Date of first construction
# inventory_dt -- Date site established or inventoried
# drain_area_va -- Drainage area
# contrib_drain_area_va -- Contributing drainage area
# tz_cd -- Time Zone abbreviation
# local_time_fg -- Site honors Daylight Savings Time
# reliability_cd -- Data reliability code
# gw_file_cd -- Data-other GW files
# nat_aqfr_cd -- National aquifer code
# aqfr_cd -- Local aquifer code
# aqfr_type_cd -- Local aquifer type code
# well_depth_va -- Well depth
# hole_depth_va -- Hole depth
# depth_src_cd -- Source of depth data
# project_no -- Project number
#

table=

	agency_cd	site_no	station_nm	site_tp_cd	lat_va	long_va	dec_lat_va	dec_long_va	coord_meth_cd	coord_acy_cd	...	local_time_fg	reliability_cd	gw_file_cd	nat_aqfr_cd	aqfr_cd	aqfr_type_cd	well_depth_va	hole_depth_va	depth_src_cd	project_no
0	USGS	01585200	WEST BRANCH HERRING RUN AT IDLEWYLDE, MD	ST	392225.1	763503.6	39.373639	-76.584333	M	S	...	Y	NaN	NNNNNNNN	NaN	NaN	NaN	NaN	NaN	NaN	NaN

1 rows × 42 columns

)