cdss-ruby 0.1.0

data/lib/cdss/surface_water.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Cdss
+  # 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).
+  module SurfaceWater
+    include Utils
+
+    # Fetches surface water stations based on various filtering criteria.
+    #
+    # @param [Hash, Array, nil] aoi Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys.
+    #   If array, must contain [longitude, latitude].
+    # @param [Integer, nil] radius Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.
+    # @param [String, nil] abbrev Station abbreviation to filter by.
+    # @param [String, nil] county County name to filter stations.
+    # @param [Integer, nil] division Water division number to filter stations.
+    # @param [String, nil] station_name Name of the station to filter by.
+    # @param [String, nil] usgs_id USGS site ID to filter by.
+    # @param [Integer, nil] water_district Water district number to filter by.
+    # @param [String, nil] api_key Optional API key for authentication.
+    # @return [Array<Station>] Array of matching surface water station objects.
+    # @raise [ArgumentError] If aoi parameter is provided but invalid.
+    # @example Fetch stations in Denver county
+    #   get_sw_stations(county: 'DENVER')
+    # @example Fetch stations within 10 miles of a point
+    #   get_sw_stations(aoi: { latitude: 39.7392, longitude: -104.9903 }, radius: 10)
+    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
+
+    # Fetches surface water time series data for specified stations.
+    #
+    # @param [String, nil] abbrev Station abbreviation.
+    # @param [String, nil] station_number Station number.
+    # @param [String, nil] usgs_id USGS site ID.
+    # @param [Date, nil] start_date Start date for time series data.
+    # @param [Date, nil] end_date End date for time series data.
+    # @param [String, nil] timescale 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
+    # @param [String, nil] api_key Optional API key for authentication.
+    # @return [Array<Reading>] Array of time series reading objects.
+    # @raise [ArgumentError] If an invalid timescale is provided.
+    # @example Fetch daily readings for a station
+    #   get_sw_ts(abbrev: 'PLAKERCO', timescale: 'day', start_date: Date.new(2023, 1, 1))
+    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
+
+    private
+
+    # Fetches daily surface water time series readings.
+    #
+    # @param [String, nil] abbrev Station abbreviation
+    # @param [String, nil] station_number Station number
+    # @param [String, nil] usgs_id USGS site ID
+    # @param [Date, nil] start_date Start date for readings
+    # @param [Date, nil] end_date End date for readings
+    # @param [String, nil] api_key Optional API key for authentication
+    # @return [Array<Reading>] Array of daily surface water readings
+    def get_sw_ts_day(abbrev: nil, station_number: nil, usgs_id: nil, start_date: nil, end_date: nil, api_key: nil)
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        abbrev: abbrev,
+        stationNum: station_number,
+        usgsSiteId: usgs_id,
+        "min-measDate": start_date&.strftime("%m-%d-%Y"),
+        "max-measDate": end_date&.strftime("%m-%d-%Y")
+      }
+
+      fetch_paginated_data(
+        endpoint: "/surfacewater/surfacewatertsday/",
+        query: query
+      ) { |data| Parser.parse_readings(data, timescale: :day) }
+    end
+
+    # Fetches monthly surface water time series readings.
+    #
+    # @param [String, nil] abbrev Station abbreviation
+    # @param [String, nil] station_number Station number
+    # @param [String, nil] usgs_id USGS site ID
+    # @param [Date, nil] start_date Start date for readings (year only)
+    # @param [Date, nil] end_date End date for readings (year only)
+    # @param [String, nil] api_key Optional API key for authentication
+    # @return [Array<Reading>] Array of monthly surface water readings
+    def get_sw_ts_month(abbrev: nil, station_number: nil, usgs_id: nil, start_date: nil, end_date: nil, api_key: nil)
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        abbrev: abbrev,
+        stationNum: station_number,
+        usgsSiteId: usgs_id,
+        "min-calYear": start_date&.strftime("%Y"),
+        "max-calYear": end_date&.strftime("%Y")
+      }
+
+      fetch_paginated_data(
+        endpoint: "/surfacewater/surfacewatertsmonth/",
+        query: query
+      ) { |data| Parser.parse_readings(data, timescale: :month) }
+    end
+
+    # Fetches water year time series readings.
+    #
+    # @param [String, nil] abbrev Station abbreviation
+    # @param [String, nil] station_number Station number
+    # @param [String, nil] usgs_id USGS site ID
+    # @param [Date, nil] start_date Start date for readings (year only)
+    # @param [Date, nil] end_date End date for readings (year only)
+    # @param [String, nil] api_key Optional API key for authentication
+    # @return [Array<Reading>] Array of water year readings
+    def get_sw_ts_wyear(abbrev: nil, station_number: nil, usgs_id: nil, start_date: nil, end_date: nil, api_key: nil)
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        abbrev: abbrev,
+        stationNum: station_number,
+        usgsSiteId: usgs_id,
+        "min-waterYear": start_date&.strftime("%Y"),
+        "max-waterYear": end_date&.strftime("%Y")
+      }
+
+      fetch_paginated_data(
+        endpoint: "/surfacewater/surfacewatertswateryear/",
+        query: query
+      ) { |data| Parser.parse_readings(data, timescale: :year) }
+    end
+  end
+end

data/lib/cdss/telemetry.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Cdss
+  # Provides methods for accessing telemetry station data from the CDSS API.
+  #
+  # This module includes functionality for retrieving telemetry stations and their
+  # associated time series data.
+  module Telemetry
+    include Utils
+
+    # Fetches telemetry stations based on various filtering criteria.
+    #
+    # @param [Hash, Array, nil] aoi Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys.
+    #   If array, must contain [longitude, latitude].
+    # @param [Integer, nil] radius Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.
+    # @param [String, nil] abbrev Station abbreviation to filter by.
+    # @param [String, nil] county County name to filter stations.
+    # @param [Integer, nil] division Water division number to filter stations.
+    # @param [String, nil] gnis_id GNIS ID to filter by.
+    # @param [String, nil] usgs_id USGS station ID to filter by.
+    # @param [Integer, nil] water_district Water district number to filter by.
+    # @param [String, nil] wdid WDID to filter by.
+    # @return [Array<Station>] Array of matching telemetry station objects.
+    # @raise [ArgumentError] If aoi parameter is provided but invalid.
+    # @example Fetch stations in Denver county
+    #   get_telemetry_stations(county: 'Denver')
+    # @example Fetch stations within 10 miles of a point
+    #   get_telemetry_stations(aoi: { latitude: 39.7392, longitude: -104.9903 }, radius: 10)
+    def get_telemetry_stations(aoi: nil, radius: nil, abbrev: nil, county: nil, division: nil, gnis_id: nil,
+                               usgs_id: nil, water_district: nil, wdid: nil)
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        includeThirdParty: true,
+        abbrev: abbrev,
+        county: county,
+        division: division,
+        gnisId: gnis_id,
+        usgsStationId: usgs_id,
+        waterDistrict: water_district,
+        wdid: wdid
+      }
+
+      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: "/telemetrystations/telemetrystation/",
+        query: query
+      ) { |data| Parser.parse_stations(data) }
+    end
+
+    # Fetches telemetry time series data for specified stations.
+    #
+    # @param [String] abbrev Station abbreviation.
+    # @param [String, nil] parameter Telemetry parameter to retrieve. Defaults to 'DISCHRG'.
+    # @param [Date, nil] start_date Start date for time series data.
+    # @param [Date, nil] end_date End date for time series data.
+    # @param [String, nil] timescale Time interval for data. Valid values: 'day', 'hour', 'raw'.
+    # @param [Boolean] include_third_party Whether to include third-party data. Defaults to true.
+    # @return [Array<Reading>] Array of time series reading objects.
+    # @raise [ArgumentError] If an invalid timescale is provided.
+    # @example Fetch daily discharge data for a station
+    #   get_telemetry_ts(abbrev: 'PLACHECO', parameter: 'DISCHRG', start_date: Date.new(2023, 1, 1))
+    def get_telemetry_ts(abbrev:, parameter: "DISCHRG", start_date: nil, end_date: nil, timescale: "day",
+                         include_third_party: true)
+      timescales = %w[day hour raw]
+      unless timescales.include?(timescale)
+        raise ArgumentError, "Invalid 'timescale' argument: '#{timescale}'. Valid values are: #{timescales.join(', ')}"
+      end
+
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        abbrev: abbrev,
+        parameter: parameter,
+        includeThirdParty: include_third_party.to_s
+      }
+
+      query[:startDate] = start_date&.strftime("%m-%d-%Y") if start_date
+      query[:endDate] = end_date&.strftime("%m-%d-%Y") if end_date
+
+      fetch_paginated_data(
+        endpoint: "/telemetrystations/telemetrytimeseries#{timescale}/",
+        query: query
+      ) { |data| Parser.parse_readings(data, timescale: timescale.to_sym) }
+    end
+  end
+end

data/lib/cdss/utils.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module Cdss
+  # Provides utility methods for handling dates, query parameters, and API pagination.
+  #
+  # This module contains helper methods used across the CDSS API client for
+  # data formatting, safe type conversion, and managing paginated responses.
+  module Utils
+    # Splits a date range into yearly chunks.
+    #
+    # @param [Date, nil] start_date Beginning of the date range
+    # @param [Date, nil] end_date End of the date range
+    # @return [Array<Array<Date>>] Array of date pairs representing yearly chunks
+    # @example Split a multi-year range
+    #   batch_dates(Date.new(2020,1,1), Date.new(2022,6,30))
+    #   #=> [[2020-01-01, 2020-12-31], [2021-01-01, 2021-12-31], [2022-01-01, 2022-06-30]]
+    def batch_dates(start_date, end_date)
+      start_date ||= Date.new(1900, 1, 1)
+      end_date ||= Date.today
+      start_year = start_date.year
+      end_year = end_date.year
+      if start_year == end_year
+        [[start_date, end_date]]
+      else
+        dates = []
+        # First year
+        dates << [start_date, Date.new(start_year, 12, 31)]
+        # Middle years
+        ((start_year + 1)...end_year).each do |year|
+          dates << [Date.new(year, 1, 1), Date.new(year, 12, 31)]
+        end
+        # Last year
+        dates << [Date.new(end_year, 1, 1), end_date]
+        dates
+      end
+    end
+
+    # Formats a query parameter value for API requests.
+    #
+    # @param [Object] value The value to format
+    # @return [String, nil] Formatted value or nil if input is nil
+    # @example Format an array parameter
+    #   format_query_param(['a', 'b']) #=> "a,b"
+    def format_query_param(value)
+      return nil if value.nil?
+      return value.join(",") if value.is_a?(Array)
+
+      value.to_s
+    end
+
+    # Builds a query hash for API requests.
+    #
+    # @param [Hash] params Query parameters to include
+    # @param [Boolean] encode Whether to URL encode parameter values
+    # @return [Hash] Query hash with formatted parameters
+    # @example Build a simple query
+    #   build_query({ name: "test", id: 123 })
+    #   #=> { format: "json", name: "test", id: "123" }
+    def build_query(params = {}, encode: false)
+      base_query = {
+        format: "json"
+      }
+      params.each do |key, value|
+        formatted_value = format_query_param(value)
+        if formatted_value
+          base_query[key] = encode ? URI.encode_www_form_component(formatted_value) : formatted_value
+        end
+      end
+      base_query
+    end
+
+    # Formats a date for API requests.
+    #
+    # @param [Date] date The date to format
+    # @param [Boolean] special_format Whether to use forward slashes instead of hyphens
+    # @return [String, nil] Formatted date string or nil if input is nil
+    # @example Format a date
+    #   format_date(Date.new(2023,1,1)) #=> "01-01-2023"
+    def format_date(date, special_format: false)
+      return nil unless date
+
+      date = date.strftime("%m-%d-%Y")
+      special_format ? date.gsub("-", "%2F") : date
+    end
+
+    # Safely parses a timestamp string.
+    #
+    # @param [String] datetime_str Timestamp string to parse
+    # @return [DateTime, nil] Parsed DateTime object or nil if parsing fails
+    # @example Parse a timestamp
+    #   parse_timestamp("2023-01-01 12:00:00")
+    def parse_timestamp(datetime_str)
+      DateTime.parse(datetime_str) if datetime_str
+    rescue ArgumentError
+      nil
+    end
+
+    # Safely converts a value to a float.
+    #
+    # @param [Object] value Value to convert
+    # @return [Float, nil] Converted float or nil if conversion fails
+    # @example Convert a string to float
+    #   safe_float("123.45") #=> 123.45
+    def safe_float(value)
+      Float(value)
+    rescue TypeError, ArgumentError
+      nil
+    end
+
+    # Safely converts a value to an integer.
+    #
+    # @param [Object] value Value to convert
+    # @return [Integer, nil] Converted integer or nil if conversion fails
+    # @example Convert a string to integer
+    #   safe_integer("123") #=> 123
+    def safe_integer(value)
+      Integer(value)
+    rescue TypeError, ArgumentError
+      nil
+    end
+
+    # Fetches all pages of data from a paginated API endpoint.
+    #
+    # @param [String] endpoint API endpoint path
+    # @param [Hash] query Query parameters for the request
+    # @yield [Hash] Block to process each page of response data
+    # @yieldreturn [Array] Processed records from the response
+    # @return [Array] Combined results from all pages
+    # @example Fetch paginated data
+    #   fetch_paginated_data(endpoint: "/api/data", query: { type: "test" }) do |data|
+    #     process_data(data)
+    #   end
+    def fetch_paginated_data(endpoint:, query:)
+      page_size = 50_000
+      page_index = 1
+      results = []
+      loop do
+        query = query.merge(pageSize: page_size, pageIndex: page_index)
+        response = get(endpoint, query: query)
+        data = handle_response(response)
+        records = yield(data)
+        break if records.empty?
+
+        results.concat(records)
+        break if records.size < page_size
+
+        page_index += 1
+      end
+      results
+    end
+  end
+end

data/lib/cdss/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Cdss
+  VERSION = "0.1.0"
+end

data/lib/cdss/water_rights.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Cdss
+  # Provides methods for accessing water rights data from the CDSS API.
+  #
+  # This module includes functionality for retrieving water rights net amounts
+  # and transactions data based on various spatial and attribute-based searches.
+  module WaterRights
+    include Utils
+
+    # Fetches water rights net amounts data based on various filtering criteria.
+    #
+    # @param [Hash, Array, nil] aoi Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys.
+    #   If array, must contain [longitude, latitude].
+    # @param [Integer, nil] radius Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.
+    # @param [String, nil] county County name to filter rights.
+    # @param [Integer, nil] division Water division number to filter rights.
+    # @param [Integer, nil] water_district Water district number to filter rights.
+    # @param [String, nil] wdid WDID code of water right.
+    # @return [Array<WaterRight>] Array of water right objects with net amounts.
+    # @raise [ArgumentError] If aoi parameter is provided but invalid.
+    def get_water_rights_net_amounts(aoi: nil, radius: nil, county: nil, division: nil, water_district: nil, wdid: nil)
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        units: "miles",
+        county: county,
+        division: division,
+        waterDistrict: water_district,
+        wdid: wdid
+      }
+      query.merge!(process_aoi(aoi, radius)) if aoi
+      fetch_paginated_data(
+        endpoint: "/waterrights/netamount/",
+        query: query
+      ) { |data| Parser.parse_water_rights(data, type: :net_amount) }
+    end
+
+    # Fetches water rights transactions data based on various filtering criteria.
+    #
+    # @param [Hash, Array, nil] aoi Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys.
+    #   If array, must contain [longitude, latitude].
+    # @param [Integer, nil] radius Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.
+    # @param [String, nil] county County name to filter transactions.
+    # @param [Integer, nil] division Water division number to filter transactions.
+    # @param [Integer, nil] water_district Water district number to filter transactions.
+    # @param [String, nil] wdid WDID code of water right.
+    # @return [Array<WaterRight>] Array of water right objects with transactions.
+    # @raise [ArgumentError] If aoi parameter is provided but invalid.
+    def get_water_rights_transactions(aoi: nil, radius: nil, county: nil, division: nil, water_district: nil, wdid: nil)
+      query = {
+        format: "json",
+        dateFormat: "spaceSepToSeconds",
+        units: "miles",
+        county: county,
+        division: division,
+        waterDistrict: water_district,
+        wdid: wdid
+      }
+      query.merge!(process_aoi(aoi, radius)) if aoi
+      fetch_paginated_data(
+        endpoint: "/waterrights/transaction/",
+        query: query
+      ) { |data| Parser.parse_water_rights(data, type: :transaction) }
+    end
+
+    private
+
+    # Processes the area of interest (AOI) parameter for spatial searches.
+    #
+    # @param [Hash, Array] aoi Area of interest with location data
+    # @param [Integer, nil] radius Search radius in miles
+    # @return [Hash] Processed location and radius query parameters
+    # @raise [ArgumentError] If AOI parameter is invalid
+    # @example Process a hash-based AOI
+    #   process_aoi({ latitude: 39.7392, longitude: -104.9903 }, 20)
+    def process_aoi(aoi, radius)
+      if aoi.is_a?(Hash) && aoi[:latitude] && aoi[:longitude]
+        {
+          longitude: aoi[:longitude],
+          latitude: aoi[:latitude],
+          radius: radius || 20
+        }
+      elsif aoi.is_a?(Array) && aoi.count == 2
+        {
+          longitude: aoi[0],
+          latitude: aoi[1],
+          radius: radius || 20
+        }
+      else
+        raise ArgumentError, "Invalid 'aoi' parameter"
+      end
+    end
+  end
+end

data/lib/cdss.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "dry-configurable"
+require "httparty"
+require "json"
+
+module Cdss
+  @loader = Zeitwerk::Loader.for_gem
+  @loader.enable_reloading
+  @loader.setup
+
+  extend Dry::Configurable
+  setting :user_agent, default: -> { "Cdss Ruby Gem/#{VERSION}" }
+  setting :timeout, default: 30
+  setting :base_url, default: "https://dwr.state.co.us/Rest/GET/api/v2"
+  setting :default_parameter, default: "DISCHRG"
+  setting :debug, default: false
+
+  class << self
+    attr_reader :loader
+
+    def client(**options)
+      Cdss::Client.new(**options)
+    end
+  end
+end

data/sig/cdss/ruby.rbs

@@ -0,0 +1,6 @@
+module Cdss
+  module Ruby
+    VERSION: String
+    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+  end
+end