dataretrieval.nwis

Functions for downloading data from the National Water Information System (NWIS).

class dataretrieval.nwis.NWIS_Metadata(response: Response, **parameters: Any)[source]

Metadata class for NWIS service, derived from BaseMetadata.

url

Response url.

Type:: str

query_time

Response elapsed time.

Type:: datetime.timedelta

header

Response headers.

Type:: httpx.Headers

comments

Metadata comments, if any.

Type:: str | None

Notes

site_info is exposed as a property (documented below) rather than a plain attribute.

__init__(response: Response, **parameters: Any) → None[source]

Generate the standard metadata set, plus NWIS-specific metadata.

Parameters:

response (Response) – Response object from the httpx module.
parameters (unpacked dictionary) – Unpacked dictionary of the parameters supplied in the request.

property site_info: tuple[DataFrame, BaseMetadata] | None

Site information for the query.

Populated when the query included site_no, sites, stateCd, huc, countyCd or bBox (site_no is preferred over sites if both are present); None otherwise.

Returns:

df (pandas.DataFrame) – Formatted requested data from calling nwis.what_sites.
md (dataretrieval.nwis.NWIS_Metadata) – A NWIS_Metadata object.

dataretrieval.nwis._build_column_name(param_cd: str, method: str, option: str | None) → str[source]: Derive the DataFrame column name for a parameter record.

dataretrieval.nwis._deprecated(func: F) → F[source]

Mark an nwis function as deprecated.

Wrappers like get_record -> get_iv -> query_waterservices would otherwise emit one warning per layer; the thread-local sentinel ensures the user sees only the outermost call’s warning.

dataretrieval.nwis._get_json_values(service: str, sites: list[str] | str | None, start: str | None, end: str | None, multi_index: bool, ssl_check: bool, kwargs: dict[str, Any]) → tuple[DataFrame, NWIS_Metadata][source]

Shared body of the JSON waterservices time-series getters (dv / iv).

The caller-facing sites / start / end arguments are aliases: an explicit waterservices keyword of the same meaning wins over them. Note that multi_index travels through kwargs so that format_response() sees it.

dataretrieval.nwis._localize_datetime_index(df: DataFrame) → DataFrame[source]: Localize a naive datetime index (or multi-index level) to UTC.

dataretrieval.nwis._parse_json_or_raise(response: Response) → DataFrame[source]: Parse a JSON NWIS response, raising a helpful error on HTML responses.

dataretrieval.nwis._parse_parameter_record(record_json: list[dict[str, Any]], col_name: str) → DataFrame[source]: Parse a single parameter’s value list into a renamed DataFrame.

dataretrieval.nwis._parse_site_block(site_block: list[dict[str, Any]]) → DataFrame[source]: Parse all timeseries in one site’s block into a single DataFrame.

dataretrieval.nwis._read_json(json: dict[str, Any]) → DataFrame[source]

Read a NWIS Water Services formatted JSON into a pandas.DataFrame.

Parameters:: json (dict) – A JSON dictionary response to be parsed into a pandas.DataFrame.
Returns:: df – Time series data from the NWIS JSON.
Return type:: pandas.DataFrame

dataretrieval.nwis._read_rdb(rdb: str) → DataFrame[source]

Parse an NWIS RDB response and apply NWIS-specific post-processing.

Thin wrapper around dataretrieval.rdb.read_rdb() that adds the NWIS column-dtype hints and runs format_response() (datetime index, multi-site MultiIndex, optional GeoDataFrame).

dataretrieval.nwis._site_block_boundaries(site_list: list[str]) → list[int][source]

Return indices where the site number changes, bookended by 0 and len.

For example, given ['A', 'A', 'B'] returns [0, 2, 3].

dataretrieval.nwis._warn_deprecated(func_name: str) → None[source]: Emit a per-function DeprecationWarning pointing at the waterdata replacement.

dataretrieval.nwis.format_response(df: DataFrame, service: str | None = None, **kwargs: Any) → DataFrame[source]

Set up the index for a query response.

Formats the response from the NWIS web services; in particular, it sets the index of the data frame. It converts the NWIS response into pandas datetime values localized to UTC and, where possible, uses those timestamps to define the data frame index.

Parameters:

df (pandas.DataFrame) – The data frame to format.
service (string, optional, default is None) – The NWIS service that was queried. This matters because the ‘peaks’ service returns a different format from the other services.
**kwargs (optional) – Additional keyword arguments, e.g. ‘multi_index’.

Returns:

df – The formatted data frame.

Return type:

pandas.DataFrame

dataretrieval.nwis.get_discharge_measurements(**kwargs: Any) → NoReturn[source]: Defunct: use waterdata.get_field_measurements().

dataretrieval.nwis.get_discharge_peaks(sites: list[str] | str | None = None, start: str | None = None, end: str | None = None, multi_index: bool = True, ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Get discharge peaks from the waterdata service.

Parameters:

sites (string or list of strings, optional, default is None) – USGS site number (or list of site numbers). If the waterdata parameter site_no is supplied, it overwrites the sites parameter.
start (string, optional, default is None) – Starting date of record (YYYY-MM-DD). If the waterdata parameter begin_date is supplied, it overwrites the start parameter.
end (string, optional, default is None) – Ending date of record (YYYY-MM-DD). If the waterdata parameter end_date is supplied, it overwrites the end parameter.
multi_index (bool, optional) – If False, return a dataframe with a single-level index (datetime). Default is True.
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Returns:

df (pandas.DataFrame) – Time series data from the NWIS JSON.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.

Examples

>>> # Get discharge peaks for site 01491000
>>> df, md = dataretrieval.nwis.get_discharge_peaks(
...     sites="01491000", start="1980-01-01", end="1990-01-01"
... )

>>> # Get discharge peaks for sites in Hawaii
>>> df, md = dataretrieval.nwis.get_discharge_peaks(
...     start="1980-01-01", end="1980-01-02", stateCd="HI"
... )

dataretrieval.nwis.get_dv(sites: list[str] | str | None = None, start: str | None = None, end: str | None = None, multi_index: bool = True, ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Get daily values data from NWIS and return it as a pandas.DataFrame.

Note

If no start or end date are provided, only the most recent record is returned.

Parameters:

sites (string or list of strings, optional, default is None) – USGS site number (or list of site numbers).
start (string, optional, default is None) – Starting date of record (YYYY-MM-DD). If the waterdata parameter startDT is supplied, it overwrites the start parameter.
end (string, optional, default is None) – Ending date of record (YYYY-MM-DD). If the waterdata parameter endDT is supplied, it overwrites the end parameter.
multi_index (bool, optional) – If True, return a multi-index dataframe; if False, return a single-index dataframe. Default is True.
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Returns:

df (pandas.DataFrame) – Time series data from the NWIS JSON.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.

Examples

>>> # Get mean statistic daily values for site 04085427
>>> df, md = dataretrieval.nwis.get_dv(
...     sites="04085427",
...     start="2012-01-01",
...     end="2012-06-30",
...     statCd="00003",
... )

>>> # Get the latest daily values for site 01646500
>>> df, md = dataretrieval.nwis.get_dv(sites="01646500")

dataretrieval.nwis.get_gwlevels(**kwargs: Any) → NoReturn[source]: Defunct: use waterdata.get_continuous(), waterdata.get_daily(), or waterdata.get_field_measurements().

dataretrieval.nwis.get_info(ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Get site description information from NWIS.

Note: Must specify one major parameter.

For additional parameter options see https://waterservices.usgs.gov/docs/site-service/site-service-details/

Parameters:

ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Keyword Arguments:

sites (string or list of strings) – A list of site numbers. Sites may be prefixed with an optional agency code followed by a colon.
stateCd (string) – U.S. postal service (2-digit) state code. Only 1 state can be specified per request.
huc (string or list of strings) – A list of hydrologic unit codes (HUC) or aggregated watersheds. Only 1 major HUC can be specified per request, or up to 10 minor HUCs. A major HUC has two digits.
bBox (string or list of strings) – A contiguous range of decimal latitude and longitude, starting with the west longitude, then the south latitude, then the east longitude, and then the north latitude, with each value separated by a comma. The product of the range of latitude and longitude cannot exceed 25 degrees. Whole or decimal degrees must be specified, up to six digits of precision. Minutes and seconds are not allowed.
countyCd (string or list of strings) – A list of county numbers, in a 5 digit numeric format. The first two digits of a county’s code are the FIPS State Code. (url: https://help.waterdata.usgs.gov/code/county_query?fmt=html)
startDt (string) – Selects sites based on whether data was collected at a point in time beginning after startDt (start date). Dates must be in ISO-8601 Calendar Date format (for example: 1990-01-01).
endDt (string) – The end date for the period of record. Dates must be in ISO-8601 Calendar Date format (for example: 1990-01-01).
period (string) – Selects sites based on whether they were active between now and a time in the past. For example, period=P10W will select sites active in the last ten weeks.
modifiedSince (string) – Returns only sites where site attributes or period of record data have changed during the request period.
parameterCd (string or list of strings) – Returns only site data for those sites containing the requested USGS parameter codes.
siteType (string or list of strings) – Restricts sites to those having one or more major and/or minor site types, such as stream, spring or well. For a list of all valid site types see https://help.waterdata.usgs.gov/site_tp_cd For example, siteType=’ST’ returns streams only.
siteOutput (string ('basic' or 'expanded')) – Indicates the richness of metadata you want for site attributes. Note that for visually oriented formats like Google Map format, this argument has no meaning. For performance reasons, siteOutput=expanded cannot be used if seriesCatalogOutput=true or with any values for outputDataTypeCd.
seriesCatalogOutput (bool) – A switch that provides detailed period of record information for certain output formats. The period of record indicates date ranges for a certain kind of information about a site, for example the start and end dates for a site’s daily mean streamflow.

Returns:

df (pandas.DataFrame) – Site data from the NWIS web service.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.

Examples

>>> # Get site information for a single site
>>> df, md = dataretrieval.nwis.get_info(sites="05114000")

>>> # Get site information for multiple sites
>>> df, md = dataretrieval.nwis.get_info(sites=["05114000", "09423350"])

dataretrieval.nwis.get_iv(sites: list[str] | str | None = None, start: str | None = None, end: str | None = None, multi_index: bool = True, ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Get instantaneous values data from NWIS and return it as a DataFrame.

Note

If no start or end date are provided, only the most recent record is returned.

Parameters:

sites (string or list of strings, optional, default is None) – USGS site number (or list of site numbers). If the waterdata parameter site_no is supplied, it overwrites the sites parameter.
start (string, optional, default is None) – Starting date of record (YYYY-MM-DD). If the waterdata parameter startDT is supplied, it overwrites the start parameter.
end (string, optional, default is None) – Ending date of record (YYYY-MM-DD). If the waterdata parameter endDT is supplied, it overwrites the end parameter.
multi_index (bool, optional) – If False, return a dataframe with a single-level index (datetime). Default is True.
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Returns:

df (pandas.DataFrame) – Time series data from the NWIS JSON.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.

Examples

>>> # Get instantaneous discharge data for site 05114000
>>> df, md = dataretrieval.nwis.get_iv(
...     sites="05114000",
...     start="2013-11-03",
...     end="2013-11-03",
...     parameterCd="00060",
... )

dataretrieval.nwis.get_pmcodes(**kwargs: Any) → NoReturn[source]: Defunct: use waterdata.get_reference_table(collection='parameter-codes').

dataretrieval.nwis.get_qwdata(**kwargs: Any) → NoReturn[source]: Defunct: use waterdata.get_samples().

dataretrieval.nwis.get_ratings(site: str | None = None, file_type: str = 'base', ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Get the rating table for an active USGS streamgage.

Reads the current rating table for an active USGS streamgage from NWISweb. Data is retrieved from https://waterdata.usgs.gov/nwis.

Parameters:

site (string, optional, default is None) – USGS site number, usually an 8 digit number as a string. If the nwis parameter site_no is supplied, it overwrites the site parameter.
file_type (string, default is "base") – One of “base”, “corr”, or “exsa”.
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Returns:

df (pandas.DataFrame) – Formatted requested data.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.

Examples

>>> # Get the rating table for USGS streamgage 01594440
>>> df, md = dataretrieval.nwis.get_ratings(site="01594440")

dataretrieval.nwis.get_record(sites: list[str] | str | None = None, start: str | None = None, end: str | None = None, multi_index: bool = True, wide_format: bool = True, datetime_index: bool = True, state: str | None = None, service: str = 'iv', ssl_check: bool = True, **kwargs: Any) → DataFrame[source]

Get data from NWIS and return it as a pandas.DataFrame.

Note

If no start or end date are provided, only the most recent record is returned.

Parameters:

sites (string or list of strings, optional, default is None) – List of sites, or a comma-delimited string of sites.
start (string, optional, default is None) – Starting date of record (YYYY-MM-DD).
end (string, optional, default is None) – Ending date of record (YYYY-MM-DD).
multi_index (bool, optional) – If False, return a dataframe with a single-level index (datetime). Default is True.
wide_format (bool, optional) – If True, return data in wide format, with multiple samples per row and one row per time. Default is True.
datetime_index (bool, optional) – If True, create a datetime index. Default is True.
state (string, optional, default is None) – State full name, abbreviation, or id.
service (string, default is 'iv') –
- ‘iv’ : instantaneous data
- ’dv’ : daily mean data
- ’site’ : site description
- ’measurements’ : (defunct) use waterdata.get_field_measurements
- ’peaks’: discharge peaks
- ’gwlevels’: (defunct) use waterdata.get_continuous, waterdata.get_daily, or waterdata.get_field_measurements
- ’pmcodes’: (defunct) use waterdata.get_reference_table
- ’water_use’: (defunct) no replacement available
- ’ratings’: get rating table
- ’stat’: get statistics
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Return type:

pandas.DataFrame containing the requested data.

Examples

>>> # Get latest instantaneous data from site 01585200
>>> df = dataretrieval.nwis.get_record(sites="01585200", service="iv")

>>> # Get latest daily mean data from site 01585200
>>> df = dataretrieval.nwis.get_record(sites="01585200", service="dv")

>>> # Get site description for site 01585200
>>> df = dataretrieval.nwis.get_record(sites="01585200", service="site")

>>> # Get discharge peaks for site 01585200
>>> df = dataretrieval.nwis.get_record(sites="01585200", service="peaks")

>>> # Get rating table for USGS streamgage 01585200
>>> df = dataretrieval.nwis.get_record(sites="01585200", service="ratings")

>>> # Get annual statistics for USGS station 01646500
>>> df = dataretrieval.nwis.get_record(
...     sites="01646500",
...     service="stat",
...     statReportType="annual",
...     statYearType="water",
... )

dataretrieval.nwis.get_stats(sites: list[str] | str | None = None, ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Query the water services statistics service.

For more information about the water services statistics service, visit https://waterservices.usgs.gov/docs/statistics/statistics-details/

Parameters:

sites (string or list of strings, optional, default is None) – USGS site number (or list of site numbers).
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Keyword Arguments:

statReportType (string) – daily (default), monthly, or annual.
statTypeCd (string) – all, mean, max, min, median.

Returns:

df (pandas.DataFrame) – Statistics data from the statistics service.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.
.. todo:: – fix date parsing

Examples

>>> # Get annual water statistics for a site
>>> df, md = dataretrieval.nwis.get_stats(
...     sites="01646500", statReportType="annual", statYearType="water"
... )

>>> # Get monthly statistics for a site
>>> df, md = dataretrieval.nwis.get_stats(
...     sites="01646500", statReportType="monthly"
... )

dataretrieval.nwis.get_water_use(**kwargs: Any) → NoReturn[source]

Defunct: use dataretrieval.nwdc.get_wateruse instead.

The legacy NWIS water-use service has been retired. Modeled water-use estimates are now served by the National Water Availability Assessment Data Companion (NWDC); retrieve them with dataretrieval.nwdc.get_wateruse().

dataretrieval.nwis.preformat_peaks_response(df: DataFrame) → DataFrame[source]

Format the datetime column of the ‘peaks’ service response.

Parameters:: df (pandas.DataFrame) – The data frame to format.
Returns:: df – The formatted data frame.
Return type:: pandas.DataFrame

dataretrieval.nwis.query_waterdata(service: str, ssl_check: bool = True, **kwargs: Any) → Response[source]

Query the waterdata service.

Parameters:

service (string) – Name of the service to query: ‘peaks’ or ‘ratings’.
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Returns:

request – The response object from the API request to the web service.

Return type:

httpx.Response

dataretrieval.nwis.query_waterservices(service: str, ssl_check: bool = True, **kwargs: Any) → Response[source]

Query waterservices.usgs.gov.

For more documentation see https://waterservices.usgs.gov/docs/

Note

User must specify one major filter: sites, stateCd, or bBox

Parameters:

service (string) – Name of the service to query: ‘dv’, ‘iv’, ‘site’, or ‘stat’.
ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Additional query parameters, if supplied.

Keyword Arguments:

bBox (string) – Bounding box of decimal latitude and longitude values, given as west longitude, south latitude, east longitude, north latitude, separated by commas.
startDT (string) – Start date (e.g. ‘2017-12-31’).
endDT (string) – End date (e.g. ‘2018-01-01’).
modifiedSince (string) – Period during which site attributes or period-of-record data must have changed for a site to be returned. Expected to be a string in ISO-8601 duration format (e.g. ‘P1D’ for one day, ‘P1Y’ for one year).

Returns:

request – The response object from the API request to the web service.

Return type:

httpx.Response

dataretrieval.nwis.what_sites(ssl_check: bool = True, **kwargs: Any) → tuple[DataFrame, NWIS_Metadata][source]

Search NWIS for sites within a region with specific data.

Parameters:

ssl_check (bool, optional) – Whether to check SSL certificates. Default is True.
**kwargs (optional) – Accepts the same parameters as dataretrieval.nwis.get_info.

Returns:

df (pandas.DataFrame) – Formatted requested data.
md (dataretrieval.nwis.NWIS_Metadata) – A custom metadata object.

Examples

>>> # get information about a single site
>>> df, md = dataretrieval.nwis.what_sites(sites="05114000")

>>> # get information about sites with phosphorus in Ohio
>>> df, md = dataretrieval.nwis.what_sites(
...     stateCd="OH", parameterCd="00665"
... )