tsgettoolbox.wdfn_read_interval_observations#

tsgettoolbox.wdfn_read_interval_observations(*, parent_time_series_id: str = None, monitoring_location_id: str = None, monitoring_location_number: str = None, agency_code: str = None, parameter_code: str = None, approval_status: Literal['Provisional', 'Approved'] = None, country_code: str = None, state_code: str = None, county_code: str = None, site_type_code: str = None, site_type_name: str = None, computation_type: str = None, start_date: str = None, end_date: str = None, next_token: str = None, interval_type: Literal['M', 'CY', 'WY'] = 'M')#

US:station::MA:USGS WDFN Statistical interval obs as time-series

Monthly statistics Monthly statistics are calculated based on the approved data for a specific month. These statistics are reported for each month of each year available. For example, statistics would be available for June 1984.

Monthly statistics represent the conditions that existed for a specific month when data was collected.

Monthly statistics available include mean of daily means, maximum of daily means, median of daily means, minimum of daily means, and percentiles for of daily mean data for each specific month in the period of record.

Annual statistics Annual statistics are calculated based on yearly records of approved data.

Annual statistics are calculated for calendar years (starting January 1) and water years (starting October 1).

Annual statistics represent the conditions that existed for a specific year (calendar or water) when data was collected.

Annual statistics available include mean of daily means, maximum of daily means, median of daily means, minimum of daily means, and percentiles of daily means for each specific year in the period of record.

Parameters:

  • parent_time_series_id –

    A unique identifier representing a single time series. This corresponds to the id field in the time-series-metadata endpoint. The parent_time_series_id returns statistics tied to a particular database entry

    Accepts Multiple Values: Multiple USGS Parent Time Series Identifiers can be specified

    Default Behavior: If no parent time series identifier is supplied, then all records matching the rest of the provided criteria will be returned.

    Examples: Return statistics tied to one particular database entry

    • &parent_time_series_id=db020040c1b746c2a635f5a53a6bb904

    Return statistics tied to multiple database entries

    • &parent_time_series_id=db020040c1b746c2a635f5a53a6bb9045&pare nt_time_series_id=db020040c1b746c2a635f5a53a6bb904

  • monitoring_location_id –

    A unique identifier representing a single monitoring location. This corresponds to the id field in the monitoring-locations endpoint. Monitoring location IDs are created by combining the agency code of the agency responsible for the monitoring location (e.g. USGS) with the ID number of the monitoring location (e.g. 02238500), separated by a hyphen (e.g. USGS-02238500). Each monitoring location has been assigned a unique station number that places them in downstream order

    Monitoring Location Identifiers can be found using this period of record Accepts Multiple Values: Multiple Monitoring Location Identifiers can be specified

    Default Behavior: If a monitoring location identifier is not supplied, then statistics will be returned for all monitoring location identifiers within the period of record

    Examples: Return statistics from a single monitoring location

    • &monitoring_location_id=USGS-01432160

    Return statistics from multiple monitoring locations

    • &monitoring_location_id=USGS- 01432160&monitoring_location_id=USGS-01432161

  • monitoring_location_number –

    An identifier representing a single monitoring location. This corresponds to the number field in the monitoring-locations endpoint. Monitoring location numbers (e.g. 02238500). Each monitoring location has been assigned a unique station number that places them in downstream order

    Monitoring Location Numbers can be found using this period of record Accepts Multiple Values: Multiple Monitoring Location Numbers can be specified

    Default Behavior: If a monitoring location number is not supplied, then statistics will be returned for all monitoring location numbers within the period of record

    Examples: Return statistics from a single monitoring location

    • &monitoring_location_number=01432160

    Return statistics from multiple monitoring locations

    • &monitoring_location_number=01432160&monitoring_location_numb er=01432161

  • agency_code – The agency that is reporting the data. Agency codes are fixed values assigned by the National Water Information System (NWIS). A list of agency codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/agency-codes/items).

  • parameter_code –

    Parameter codes are 5-digit codes used to identify the constituent measured and the units of measure. A complete list of parameter codes and associated groupings can be found at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/parameter-codes/items). Accepts Multiple Values: Multiple USGS parameter codes can be specified

    Default Behavior: If no USGS parameter code is specified, but a Monitoring Location Identifier is supplied, then all statistics and their parameter codes with a matching monitoring location identifier will be returned. All statistics within the period of record will be returned if no parameter code or monitoring location identifier are specified.

    Examples: Return statistics from one matching USGS parameter code

    • &parameter_code=00095

    Return statistics from multiple matching USGS parameter codes

    • &parameter_code=00095&parameter_code=0009

  • approval_status –

    Whether to include approved and/or provisional observations. At this time, only approved observations are returned. Accepts Multiple Values:Multiple approval_status values can be specified as separate parameter-value pairs. Default Behavior: Approved observations are included by default. Example: Only include approved observations

    • &approval_status=approved

    Available values: approved

  • country_code –

    If one of country, county, or state code is supplied then the other two arguments do not need to be specified Accepts Multiple Values: Multiple Country codes can be specified

    Default Behavior: US will be specified by default.

    Examples: Return statics from one country

    • &country_code=US

    Return statistics from multiple countries

    • &country_code=US&country_code=CA

  • state_code –

    State code. A [two-digit ANSI code](https://www2.census.gov/geo/docs/reference/state.txt) (formerly FIPS code) as defined by the American National Standards Institute, to define States and equivalents. A three-digit ANSI code is used to define counties and county equivalents. [A lookup table is available.](https://www.census.gov/library/reference/code- lists/ansi.html#states) The only countries with political subdivisions other than the US are Mexico and Canada. The Mexican states have US state codes ranging from 81-86 and Canadian provinces have state codes ranging from 90-98. Accepts Multiple Values: Multiple State codes can be specified

    Default Behavior: US:42 will be specified by default.

    Examples: Return statistics from one state

    • &state_code=US:42

    Return statistics in multiple states

    • &state_code=US:42&state_code=US:36

  • county_code –

    The code for the county or county equivalent (parish, borough, etc.) in which the monitoring location is located. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/counties/items). Accepts Multiple Values: Multiple County codes can be specified

    Default Behavior: US:42:103 will be specified by default.

    Examples: Return statistics from one county

    • &county_code=US:42:103

    Return statistics from multiple counties

    • &county_code=US:42:103&county_code=US:42:105

  • site_type_code –

    A code describing the hydrologic setting of the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items). Accepts Multiple Values: Multiple Site Type Codes can be specified

    Default Behavior: If no Site Type code is specified, statistics of all site types with the matching Monitoring Location Identifier will be returned.

    Examples: Return statistics with matching site type code

    • &site_type_code=GW

    Return statistics with matching site type codes

    • &site_type_code=GW&site_type_code=ST

  • site_type_name –

    A description of the hydrologic setting of the monitoring location. A list of codes is available at [https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items](https://api.waterdata.usgs.gov/ogcapi/v0/collections/site-types/items). Accepts Multiple Values: Multiple Site Type Names can be specified

    Default Behavior: If no Site Type name is specified, statistics of all site types with the matching Monitoring Location Identifier will be returned

    Examples: Return statistics with matching site type name

    • &site_type_name=Well

    Return statistics with multiple matching site type names

    • &site_type_name=Well&site_type_name=Spring

  • computation_type –

    Statistical computation method Accepts Multiple Values: Multiple computation types can be specified

    Default Behavior: All statistical computation types are returned by default.

    Examples: Only return arithmetic_mean calculations

    • &computation_type=arithmetic_mean

    Only return maximum calculations

    • &computation_type=maximum

    Only return median calculations

    • &computation_type=median

    Only return minimum calculations

    • &computation_type=minimum

    Only return percentile calculations

    • &computation_type=percentile

    Return multiple calculations

    • &computation_type=arithmetic_mean&computation_type=median

    Available values : arithmetic_mean, maximum, median, minimum, percentile

  • start_date –

    The logic is inclusive i.e it will also return records that match the date Default Behavior: If an end date is supplied, but no start date is supplied, then statistics will be supplied for the entire period of record ending with the end date. If an end date is not supplied, but a start date is supplied then statistics will be supplied for the period of record following the start date. If no start or end date are supplied then statistics will be supplied for the entire period of record.

    Example: Return statistics starting on a particular start date

    • &start_date=02-04

  • end_date –

    The logic is inclusive i.e it will also return records that match the date Default Behavior: If an end date is supplied, but no start date is supplied, then statistics will be supplied for the entire period of record ending with the end date. If an end date is not supplied, but a start date is supplied then statistics will be supplied for the period of record following the start date. If no start or end date are supplied then statistics will be supplied for the entire period of record.

    Example: Return statistics starting on a particular start date

    • &end_date=03-04

  • next_token –

    Randomly generated token value of numbers and digits

    To get all pages, one is required to make continued requests with the newly provided token until the last resulting page where no nextToken is present Default Behavior: Provided in the event of results exceeding the default or specified page_size.

    Example: Returned token for next set of results

    • A43kJRTn26nT46fyj4ug1A

  • interval_type –

    Default Behavior: Defaults to ‘M’ Filters the results to one of the following intervals: M for month, CY for calendar year, WY for water year

    Examples: Return month interval

    • &interval_type=M

    Return calendar year interval

    • &interval_type=CY

    Return water year interval

    • &interval_type=WY

    Available values : M, CY, WY