Module: Cdss::SurfaceWater

Includes:
Utils
Included in:
Client
Defined in:
lib/cdss/surface_water.rb

Overview

Provides methods for accessing surface water data from the CDSS API.

This module includes functionality for retrieving surface water stations and their associated time series data at various time scales (daily, monthly, yearly).

Instance Method Summary collapse

Methods included from Utils

#batch_dates, #build_query, #fetch_paginated_data, #format_date, #format_query_param, #parse_timestamp, #safe_float, #safe_integer

Instance Method Details

#get_sw_stations(aoi: nil, radius: nil, abbrev: nil, county: nil, division: nil, station_name: nil, usgs_id: nil, water_district: nil, api_key: nil) ⇒ Array<Station>

Fetches surface water stations based on various filtering criteria.

Examples:

Fetch stations in Denver county

get_sw_stations(county: 'DENVER')

Fetch stations within 10 miles of a point

get_sw_stations(aoi: { latitude: 39.7392, longitude: -104.9903 }, radius: 10)

Parameters:

  • aoi (Hash, Array, nil) (defaults to: nil) —

    Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys. If array, must contain [longitude, latitude].

  • radius (Integer, nil) (defaults to: nil) —

    Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.

  • abbrev (String, nil) (defaults to: nil) —

    Station abbreviation to filter by.

  • county (String, nil) (defaults to: nil) —

    County name to filter stations.

  • division (Integer, nil) (defaults to: nil) —

    Water division number to filter stations.

  • station_name (String, nil) (defaults to: nil) —

    Name of the station to filter by.

  • usgs_id (String, nil) (defaults to: nil) —

    USGS site ID to filter by.

  • water_district (Integer, nil) (defaults to: nil) —

    Water district number to filter by.

  • api_key (String, nil) (defaults to: nil) —

    Optional API key for authentication.

Returns:

  • (Array<Station>) —

    Array of matching surface water station objects.

Raises:

  • (ArgumentError) —

    If aoi parameter is provided but invalid.



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
 
# File 'lib/cdss/surface_water.rb', line 29

def get_sw_stations(aoi: nil, radius: nil, abbrev: nil, county: nil, division: nil, station_name: nil,
                    usgs_id: nil, water_district: nil, api_key: nil)
  query = {
    format: "json",
    dateFormat: "spaceSepToSeconds",
    abbrev: abbrev,
    county: county,
    division: division,
    stationName: station_name,
    usgsSiteId: usgs_id,
    waterDistrict: water_district
  }

  if aoi
    if aoi.is_a?(Hash) && aoi[:latitude] && aoi[:longitude]
      query.merge!(longitude: aoi[:longitude], latitude: aoi[:latitude])
    elsif aoi.is_a?(Array) && aoi.count == 2
      query.merge!(longitude: aoi[0], latitude: aoi[1])
    else
      raise ArgumentError, "Invalid 'aoi' parameter"
    end
    query[:radius] = radius || 20
    query[:units] = "miles"
  end

  fetch_paginated_data(
    endpoint: "/surfacewater/surfacewaterstations/",
    query: query
  ) { |data| Parser.parse_stations(data) }
end

#get_sw_ts(abbrev: nil, station_number: nil, usgs_id: nil, start_date: nil, end_date: nil, timescale: nil, api_key: nil) ⇒ Array<Reading>

Fetches surface water time series data for specified stations.

Examples:

Fetch daily readings for a station

get_sw_ts(abbrev: 'PLAKERCO', timescale: 'day', start_date: Date.new(2023, 1, 1))

Parameters:

  • abbrev (String, nil) (defaults to: nil) —

    Station abbreviation.

  • station_number (String, nil) (defaults to: nil) —

    Station number.

  • usgs_id (String, nil) (defaults to: nil) —

    USGS site ID.

  • start_date (Date, nil) (defaults to: nil) —

    Start date for time series data.

  • end_date (Date, nil) (defaults to: nil) —

    End date for time series data.

  • timescale (String, nil) (defaults to: nil) —

    Time interval for data aggregation. Valid values:

    • day, days, daily, d

    • month, months, monthly, mon, m

    • wyear, water_year, wyears, water_years, wateryear, wateryears, wy, year, years, yearly, annual, annually, yr, y

  • api_key (String, nil) (defaults to: nil) —

    Optional API key for authentication.

Returns:

  • (Array<Reading>) —

    Array of time series reading objects.

Raises:

  • (ArgumentError) —

    If an invalid timescale is provided.



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/cdss/surface_water.rb', line 76

def get_sw_ts(abbrev: nil, station_number: nil, usgs_id: nil, start_date: nil, end_date: nil, timescale: nil,
              api_key: nil)
  timescale ||= "day"

  day_lst = %w[day days daily d]
  month_lst = %w[month months monthly mon m]
  year_lst = %w[wyear water_year wyears water_years wateryear wateryears wy year years
                yearly annual annually yr y]
  timescale_lst = day_lst + month_lst + year_lst

  unless timescale_lst.include?(timescale)
    valid_timescales = timescale_lst.join(", ")
    raise ArgumentError, "Invalid 'timescale' argument: '#{timescale}'. Valid values are: #{valid_timescales}"
  end

  case timescale
  when *day_lst
    get_sw_ts_day(abbrev: abbrev, station_number: station_number, usgs_id: usgs_id, start_date: start_date,
                  end_date: end_date, api_key: api_key)
  when *month_lst
    get_sw_ts_month(abbrev: abbrev, station_number: station_number, usgs_id: usgs_id, start_date: start_date,
                    end_date: end_date, api_key: api_key)
  when *year_lst
    get_sw_ts_wyear(abbrev: abbrev, station_number: station_number, usgs_id: usgs_id, start_date: start_date,
                    end_date: end_date, api_key: api_key)
  else
    raise ArgumentError, "Invalid 'timescale' argument: '#{timescale}'"
  end
end