tsgettoolbox.wdfn_read_normal_observations#

tsgettoolbox.wdfn_read_normal_observations(*, parent_time_series_id: str = None, monitoring_location_id: 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, normal_type: Literal['DOY', 'MOY'] = 'DOY')#

US:station::DM:USGS WDFN Statistical normal observations

Day of year statistics Day of year statistics are calculated based on all approved historic observations for a numeric day of the year. For example, January 1, is day 1 of a calendar year and December 31 is day 365 of a non-leap year.

Day of year statistics represent the expected conditions for a generic day of the year at a location based on approved historical observations.

Day of year statistics available include the daily mean of daily means, daily maximum of daily means, daily median of daily means, daily minimum of daily means, and daily percentiles of daily means based on the same numeric day of the year in the period of record.

Month of year statistics Month of year statistics are calculated based on all approved historic observations within a given month. For example, all October data ever collected and approved at a monitoring location would be included in one set of monthly statistics.

Month of year statistics represent the expected conditions for a generic month of the year at a location based on approved historical observations.

Month of year statistics available include monthly mean of daily means, monthly median of daily means, monthly maximum of daily means, monthly minimum of daily means, and monthly percentiles of daily means based on the same month 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

  • 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

  • normal_type –

    Default Behavior: Defaults to ‘DOY’

    It will filter the results to one of the following normals: (DOY) for day-of-year, (MOY) for month-of-year.

    Examples: Return day-of-year statistics only

    • &normal_type=DOY

    Return month-of-year statistics only

    • &normal_type=MOY

    Available values : DOY, MOY