USGS

The United States Geological Survey’s (USGS) National Water Information System (NWIS) provides different categories of water data for sites all across the US. This includes information about both surface and ground water, and for physical, chemical, and pollution variables. searvey uses NWIS REST API through dataretrieval package to access this data. Currently only data about elevation and flow rate are exposed in searvey.

A list of USGS stations is provided with the get_usgs_stations() function with various subsetting options.

searvey.usgs.get_usgs_stations(region: Polygon | MultiPolygon | None = None, lon_min: float | None = None, lon_max: float | None = None, lat_min: float | None = None, lat_max: float | None = None) → GeoDataFrame

Return USGS station metadata from: https://waterservices.usgs.gov/rest/Site-Service.html

If region is defined then the stations that are outside of the region are filtered out. If the coordinates of the Bounding Box are defined then stations outside of the BBox are filtered out. If both region and the Bounding Box are defined, then an exception is raised.

Note: The longitudes of the USGS stations are in the [-180, 180] range.

Parameters:

  • region – Polygon or MultiPolygon denoting region of interest

  • lon_min – The minimum Longitude of the Bounding Box.

  • lon_max – The maximum Longitude of the Bounding Box.

  • lat_min – The minimum Latitude of the Bounding Box.

  • lat_max – The maximum Latitude of the Bounding Box.

Returns:

geopandas.GeoDataFrame with the station metadata

The station data can be retrieved with

searvey.usgs.get_usgs_data(usgs_metadata: ~pandas.core.frame.DataFrame, endtime: str | ~datetime.date | ~datetime.datetime | ~pandas._libs.tslibs.timestamps.Timestamp = 'now', period: float = 1, rate_limit: ~searvey.rate_limit.RateLimit = <searvey.rate_limit.RateLimit object>, disable_progress_bar: bool = False) → Dataset

Return the data of the stations specified in usgs_metadata as an xr.Dataset.

Parameters:

  • usgs_metadata – A pd.DataFrame returned by get_usgs_stations.

  • endtime – The date of the “end” of the data. Defaults to datetime.date.today()

  • period – The number of days to be requested. USGS does not support values greater than 30

  • rate_limit – The default rate limit is 5 requests/second.

  • disable_progress_bar – If True then the progress bar is not displayed.

Returns:

xr.Dataset of station measurements