cdss-ruby 0.1.0

data/lib/cdss/parsers/structures_parser.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module StructuresParser
+      extend BaseParser
+
+      class << self
+        def parse_structures(response)
+          parse_collection(response) { |data| build_structure(data) }
+        end
+
+        def parse_diversion_records(response, type:)
+          parse_collection(response) { |data| build_diversion_record(data, type) }
+        end
+
+        def parse_water_classes(response)
+          parse_collection(response) { |data| build_water_class(data) }
+        end
+
+        private
+
+        def build_structure(data)
+          Models::Structure.new(
+            wdid: data["wdid"],
+            structure_name: data["structureName"],
+            structure_type: data["structureType"],
+            water_source: data["waterSource"],
+            division: safe_integer(data["division"]),
+            water_district: safe_integer(data["waterDistrict"]),
+            county: data["county"],
+            designated_basin: data["designatedBasin"],
+            management_district: data["managementDistrict"],
+            latitude: safe_float(data["latitude"]),
+            longitude: safe_float(data["longitude"]),
+            utm_x: safe_float(data["utmX"]),
+            utm_y: safe_float(data["utmY"]),
+            stream_num: data["streamNum"],
+            structure_num: data["structureNum"],
+            ciu_code: data["ciuCode"],
+            ciucode_desc: data["ciucodeDesc"],
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+
+        def build_diversion_record(data, type)
+          Models::DiversionRecord.new(
+            wdid: data["wdid"],
+            water_class_num: safe_integer(data["waterClassNum"]),
+            wc_identifier: data["wcIdentifier"],
+            meas_interval: data["measInterval"],
+            meas_count: safe_integer(data["measCount"]),
+            data_meas_date: parse_data_meas_date(data["dataMeasDate"], type),
+            data_value: safe_float(data["dataValue"]),
+            meas_units: data["measUnits"],
+            obs_code: data["obsCode"],
+            approval_status: data["approvalStatus"],
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+
+        def build_water_class(data)
+          Models::WaterClass.new(
+            wdid: data["wdid"],
+            wc_identifier: data["wcIdentifier"],
+            por_start: parse_timestamp(data["porStart"]),
+            por_end: parse_timestamp(data["porEnd"]),
+            div_type: data["divrectype"],
+            timestep: data["timestep"],
+            units: data["units"],
+            source_code: data["sourceCode"],
+            use_code: data["useCode"],
+            op_code: data["opCode"],
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+
+        def parse_data_meas_date(date_str, type)
+          return nil if date_str.nil?
+
+          case type
+          when :year
+            parse_timestamp("#{date_str}-01-01 00:00:00")
+          when :month
+            parse_timestamp("#{date_str}-01 00:00:00")
+          else
+            parse_timestamp(date_str)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/water_rights_parser.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module WaterRightsParser
+      extend BaseParser
+
+      class << self
+        def parse_water_rights(response, type:)
+          parse_collection(response) do |data|
+            case type
+            when :net_amount
+              build_net_amount(data)
+            when :transaction
+              build_transaction(data)
+            else
+              raise ArgumentError, "Invalid water rights type: #{type}"
+            end
+          end
+        end
+
+        private
+
+        def build_net_amount(data)
+          Cdss::Models::WaterRight.new(
+            wdid: data["wdid"],
+            water_right_name: data["waterRightName"],
+            admin_number: data["adminNumber"]&.to_f,
+            appropriation_date: parse_timestamp(data["appropriationDate"]),
+            padj_date: parse_timestamp(data["padjDate"]),
+            adj_type: data["adjType"],
+            order_number: data["orderNumber"],
+            prior_cases: data["priorCases"],
+            adj_date: parse_timestamp(data["adjDate"]),
+            status: data["status"],
+            decreed_uses: data["decreedUses"],
+            decreed_amount: data["decreedAmount"]&.to_f,
+            decreed_units: data["decreedUnits"],
+            county: data["county"],
+            water_district: data["waterDistrict"]&.to_i,
+            division: data["division"]&.to_i,
+            stream_mile: data["streamMile"]&.to_f,
+            structure_type: data["structureType"],
+            latitude: data["latitude"]&.to_f,
+            longitude: data["longitude"]&.to_f,
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+
+        def build_transaction(data)
+          Cdss::Models::WaterRight.new(
+            wdid: data["wdid"],
+            water_right_name: data["waterRightName"],
+            trans_id: data["transId"],
+            trans_type: data["transType"],
+            case_number: data["caseNumber"],
+            adj_date: parse_timestamp(data["adjDate"]),
+            admin_number: data["adminNumber"]&.to_f,
+            order_number: data["orderNumber"],
+            prior_cases: data["priorCases"],
+            decreed_uses: data["decreedUses"],
+            decreed_amount: data["decreedAmount"]&.to_f,
+            decreed_units: data["decreedUnits"],
+            action_comment: data["actionComment"],
+            action_update: data["actionUpdate"],
+            county: data["county"],
+            water_district: data["waterDistrict"]&.to_i,
+            division: data["division"]&.to_i,
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cdss/parsers/well_parser.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Cdss
+  module Parsers
+    module WellParser
+      extend BaseParser
+
+      class << self
+        def parse_wells(response)
+          parse_collection(response)
+        end
+
+        def parse_well_measurements(response)
+          parse_collection(response) { |data| build_measurement(data) }
+        end
+
+        def parse_geophysical_wells(response)
+          parse_collection(response) { |data| build_geophysical_well(data) }
+        end
+
+        def parse_log_picks(response)
+          parse_collection(response) { |data| build_log_pick(data) }
+        end
+
+        private
+
+        def build_resource(data)
+          Cdss::Models::Well.new(
+            well_id: data["wellId"],
+            well_name: data["wellName"],
+            latitude: data["latitude"],
+            longitude: data["longitude"],
+            location_accuracy: data["locationAccuracy"],
+            county: data["county"],
+            designated_basin: data["designatedBasin"],
+            management_district: data["managementDistrict"],
+            division: data["division"],
+            water_district: data["waterDistrict"],
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+
+        def build_measurement(data)
+          Cdss::Models::Reading.new(
+            well_id: data["wellId"],
+            well_name: data["wellName"],
+            division: data["division"],
+            water_district: data["waterDistrict"],
+            county: data["county"],
+            management_district: data["managementDistrict"],
+            designated_basin: data["designatedBasin"],
+            publication: data["publication"],
+            measurement_date: parse_timestamp(data["measurementDate"]),
+            depth_to_water: safe_float(data["depthToWater"]),
+            measuring_point_above_land_surface: safe_float(data["measuringPointAboveLandSurface"]),
+            depth_water_below_land_surface: safe_float(data["depthWaterBelowLandSurface"]),
+            elevation_of_water: safe_float(data["elevationOfWater"]),
+            delta: safe_float(data["delta"]),
+            modified: parse_timestamp(data["modified"]),
+            data_source: data["dataSource"],
+            metadata: {}
+          )
+        end
+
+        def build_geophysical_well(data)
+          Cdss::Models::Well.new(
+            well_id: data["wellId"],
+            well_name: data["wellName"],
+            latitude: data["latitude"],
+            longitude: data["longitude"],
+            location_accuracy: data["locationAccuracy"],
+            county: data["county"],
+            designated_basin: data["designatedBasin"],
+            management_district: data["managementDistrict"],
+            division: data["division"],
+            water_district: data["waterDistrict"],
+            depth: safe_float(data["totalDepth"]),
+            elevation: safe_float(data["groundElevation"]),
+            modified: parse_timestamp(data["modified"]),
+            metadata: {}
+          )
+        end
+
+        def build_log_pick(data)
+          Cdss::Models::Reading.new(
+            well_id: data["wellId"],
+            pick_depth: safe_float(data["pickDepth"]),
+            formation: data["formation"],
+            member: data["member"],
+            pick_quality: data["pickQuality"],
+            comments: data["comments"],
+            modified: parse_timestamp(data["modified"]),
+            aquifer: data["aquifer"],
+            g_log_top_depth: safe_float(data["gLogTopDepth"]),
+            g_log_base_depth: safe_float(data["gLogBaseDepth"]),
+            g_log_top_elev: safe_float(data["gLogTopElev"]),
+            g_log_base_elev: safe_float(data["gLogBaseElev"]),
+            g_log_thickness: safe_float(data["gLogThickness"]),
+            comment: data["comment"],
+            metadata: {}
+          )
+        end
+      end
+    end
+  end
+end

data/lib/cdss/reference_tables.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Cdss
+  # Provides access to reference tables from the CDSS API.
+  # These tables provide metadata and lookup information for various CDSS resources.
+  module ReferenceTables
+    include Utils
+
+    # List of valid reference table names that can be queried
+    VALID_TABLES = %w[
+      county
+      waterdistricts
+      waterdivisions
+      designatedbasins
+      managementdistricts
+      telemetryparams
+      climateparams
+      divrectypes
+      flags
+    ].freeze
+
+    # Fetches reference table data from the CDSS API.
+    #
+    # @param [String] table_name The name of the reference table to fetch.
+    #   Must be one of: county, waterdistricts, waterdivisions, designatedbasins,
+    #   managementdistricts, telemetryparams, climateparams, divrectypes, flags
+    # @param [Hash] params Additional parameters for filtering table data
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of reference table records
+    # @raise [ArgumentError] If an invalid table name is provided
+    def get_reference_table(table_name, **params)
+      validate_table_name!(table_name)
+      method_name = "fetch_#{table_name}_reference"
+      send(method_name, **params)
+    end
+
+    private
+
+    # Validates that the requested table name is supported.
+    #
+    # @param [String] table_name Name of table to validate
+    # @raise [ArgumentError] If table_name is not in VALID_TABLES list
+    def validate_table_name!(table_name)
+      return if VALID_TABLES.include?(table_name)
+
+      raise ArgumentError,
+            "Invalid table_name: #{table_name}. Valid values are: #{VALID_TABLES.join(', ')}"
+    end
+
+    # Fetches county reference data.
+    #
+    # @param [String, nil] county County name to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of county records
+    def fetch_county_reference(county: nil)
+      query = build_query({ county: county })
+      fetch_reference_data("/referencetables/county/", query)
+    end
+
+    # Fetches water district reference data.
+    #
+    # @param [Integer, nil] division Division to filter by
+    # @param [Integer, nil] water_district Water district to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of water district records
+    def fetch_waterdistricts_reference(division: nil, water_district: nil)
+      query = build_query(
+        {
+          division: division,
+          waterDistrict: water_district
+        }
+      )
+      fetch_reference_data("/referencetables/waterdistrict/", query)
+    end
+
+    # Fetches water division reference data.
+    #
+    # @param [Integer, nil] division Division to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of water division records
+    def fetch_waterdivisions_reference(division: nil)
+      query = build_query({ division: division })
+      fetch_reference_data("/referencetables/waterdivision/", query)
+    end
+
+    # Fetches management district reference data.
+    #
+    # @param [String, nil] management_district Management district name to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of management district records
+    def fetch_managementdistricts_reference(management_district: nil)
+      query = build_query({ managementDistrictName: management_district })
+      fetch_reference_data("/referencetables/managementdistrict/", query)
+    end
+
+    # Fetches designated basin reference data.
+    #
+    # @param [String, nil] designated_basin Designated basin name to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of designated basin records
+    def fetch_designatedbasins_reference(designated_basin: nil)
+      query = build_query({ designatedBasinName: designated_basin })
+      fetch_reference_data("/referencetables/designatedbasin/", query)
+    end
+
+    # Fetches telemetry parameter reference data.
+    #
+    # @param [String, nil] param Parameter name to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of telemetry parameter records
+    def fetch_telemetryparams_reference(param: nil)
+      query = build_query({ parameter: param })
+      fetch_reference_data("/referencetables/telemetryparams/", query)
+    end
+
+    # Fetches climate parameter reference data.
+    #
+    # @param [String, nil] param Climate parameter type to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of climate parameter records
+    def fetch_climateparams_reference(param: nil)
+      query = build_query({ measType: param })
+      fetch_reference_data("/referencetables/climatestationmeastype/", query)
+    end
+
+    # Fetches diversion record type reference data.
+    #
+    # @param [String, nil] divrectype Record type to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of diversion record type records
+    def fetch_divrectypes_reference(divrectype: nil)
+      query = build_query({ divRecType: divrectype })
+      fetch_reference_data("/referencetables/divrectypes/", query)
+    end
+
+    # Fetches station flag reference data.
+    #
+    # @param [String, nil] flag Flag to filter by
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of station flag records
+    def fetch_flags_reference(flag: nil)
+      query = build_query({ flag: flag })
+      fetch_reference_data("/referencetables/stationflags/", query)
+    end
+
+    # Fetches and parses reference table data from an endpoint.
+    #
+    # @param [String] endpoint API endpoint path
+    # @param [Hash] query Query parameters for the request
+    # @return [Array<Cdss::Models::ReferenceTable>] Array of reference table records
+    def fetch_reference_data(endpoint, query)
+      fetch_paginated_data(endpoint: endpoint, query: query) do |data|
+        Parser.parse_reference_table(data)
+      end
+    end
+  end
+end

data/lib/cdss/structures.rb

@@ -0,0 +1,235 @@
+# frozen_string_literal: true
+
+module Cdss
+  # Provides methods for accessing water structures data from the CDSS API.
+  #
+  # This module includes functionality for retrieving water structures,
+  # diversion records, stage/volume data, and water classes.
+  module Structures
+    include Utils
+
+    # Fetches a list of administrative structures based on various filtering criteria.
+    #
+    # @param [Hash, Array, nil] aoi Area of interest for spatial searches. If hash, must contain :latitude and :longitude keys.
+    # @param [Integer, nil] radius Radius in miles for spatial search around aoi. Defaults to 20 if aoi is provided.
+    # @param [String, nil] county County to filter structures.
+    # @param [Integer, nil] division Water division to filter structures.
+    # @param [String, nil] gnis_id GNIS ID to filter structures.
+    # @param [Integer, nil] water_district Water district to filter structures.
+    # @param [String, Array<String>, nil] wdid WDID code(s) to filter specific structures.
+    # @return [Array<Models::Structure>] Array of matching structures.
+    # @raise [ArgumentError] If aoi parameter is provided but invalid.
+    def get_structures(aoi: nil, radius: nil, county: nil, division: nil, gnis_id: nil, water_district: nil, wdid: nil)
+      query = build_query({
+                            county: county,
+                            division: division,
+                            gnisId: gnis_id,
+                            waterDistrict: water_district,
+                            wdid: Array(wdid).join("%2C+"),
+                            units: "miles"
+                          })
+
+      if aoi
+        coords = process_aoi(aoi)
+        query.merge!({
+                       latitude: coords[:lat],
+                       longitude: coords[:lng],
+                       radius: radius || 20
+                     })
+      end
+
+      fetch_paginated_data(
+        endpoint: "/structures/",
+        query: query
+      ) do |data|
+        Parser.parse_structures(data)
+      end
+    end
+
+    # Fetches diversion records time series data.
+    #
+    # @param [String, Array<String>] wdid WDID code(s) of structures.
+    # @param [String, nil] wc_identifier Water class identifier.
+    # @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 ('day', 'month', or 'year'). Defaults to 'day'.
+    # @return [Array<Models::DiversionRecord>] Array of diversion records.
+    # @raise [ArgumentError] If an invalid timescale is provided.
+    def get_diversion_records_ts(wdid:, wc_identifier: nil, start_date: nil, end_date: nil, timescale: "day")
+      validate_timescale!(timescale)
+
+      method_name = "fetch_diversion_records_#{timescale}"
+      send(method_name, wdid: wdid, wc_identifier: wc_identifier, start_date: start_date, end_date: end_date)
+    end
+
+    # Fetches stage/volume record data.
+    #
+    # @param [String] wdid WDID code of structure.
+    # @param [Date, nil] start_date Start date for records.
+    # @param [Date, nil] end_date End date for records.
+    # @return [Array<Models::DiversionRecord>] Array of stage/volume records.
+    def get_stage_volume_ts(wdid:, start_date: nil, end_date: nil)
+      query = build_query({
+                            wdid: wdid,
+                            "min-dataMeasDate": format_date(start_date),
+                            "max-dataMeasDate": format_date(end_date)
+                          })
+
+      fetch_paginated_data(
+        endpoint: "/structures/divrec/stagevolume/",
+        query: query
+      ) do |data|
+        Parser.parse_diversion_records(data, type: :stage_volume)
+      end
+    end
+
+    # Fetches water classes for structures.
+    #
+    # @param [Hash] params Query parameters including wdid, county, division, etc.
+    # @option params [String, Array<String>] :wdid WDID code(s) to filter by
+    # @option params [String] :county County name to filter by
+    # @option params [Integer] :division Division number to filter by
+    # @option params [Integer] :water_district Water district to filter by
+    # @option params [String] :wc_identifier Water class identifier
+    # @option params [String] :timestep Time step for records
+    # @option params [Date] :start_date Start date for records
+    # @option params [Date] :end_date End date for records
+    # @option params [String] :divrectype Diversion record type
+    # @option params [String] :ciu_code CIU code
+    # @option params [String] :gnis_id GNIS ID
+    # @option params [Hash, Array] :aoi Area of interest for spatial search
+    # @option params [Integer] :radius Radius in miles for spatial search
+    # @return [Array<Models::WaterClass>] Array of water classes.
+    def get_water_classes(**params)
+      query = build_query({
+                            wdid: Array(params[:wdid]).join("%2C+"),
+                            county: params[:county],
+                            division: params[:division],
+                            waterDistrict: params[:water_district],
+                            wcIdentifier: format_wc_identifier(params[:wc_identifier]),
+                            timestep: params[:timestep],
+                            "min-porStart": format_date(params[:start_date]),
+                            "min-porEnd": format_date(params[:end_date]),
+                            divrectype: params[:divrectype],
+                            ciuCode: params[:ciu_code],
+                            gnisId: params[:gnis_id]
+                          })
+
+      if params[:aoi]
+        coords = process_aoi(params[:aoi])
+        query.merge!({
+                       latitude: coords[:lat],
+                       longitude: coords[:lng],
+                       radius: params[:radius] || 20,
+                       units: "miles"
+                     })
+      end
+
+      fetch_paginated_data(
+        endpoint: "/structures/divrec/waterclasses/",
+        query: query
+      ) do |data|
+        Parser.parse_water_classes(data)
+      end
+    end
+
+    private
+
+    # Validates the provided timescale against allowed values.
+    #
+    # @param [String] timescale The timescale to validate
+    # @raise [ArgumentError] If timescale is not a valid value
+    def validate_timescale!(timescale)
+      valid_timescales = {
+        "day" => %w[day days daily d],
+        "month" => %w[month months monthly mon m],
+        "year" => %w[year years yearly annual annually yr y]
+      }
+
+      normalized = timescale.to_s.downcase
+      return if valid_timescales.values.flatten.include?(normalized)
+
+      raise ArgumentError,
+            "Invalid timescale: #{timescale}. Valid values are: #{valid_timescales.values.flatten.join(', ')}"
+    end
+
+    # Formats a water class identifier for API queries.
+    #
+    # @param [String, nil] identifier The identifier to format
+    # @return [String] Formatted identifier for API use
+    def format_wc_identifier(identifier)
+      return "*diversion*" if identifier.nil?
+      return "diversion" if %w[diversion diversions div divs d].include?(identifier.downcase)
+      return "release" if %w[release releases rel rels r].include?(identifier.downcase)
+
+      "*#{identifier}*"
+    end
+
+    # Fetches daily diversion records.
+    #
+    # @param [String, Array<String>] wdid WDID code(s)
+    # @param [String] wc_identifier Water class identifier
+    # @param [Date, nil] start_date Start date for records
+    # @param [Date, nil] end_date End date for records
+    # @return [Array<Models::DiversionRecord>] Array of daily diversion records
+    def fetch_diversion_records_day(wdid:, wc_identifier:, start_date:, end_date:)
+      query = build_diversion_query(wdid, wc_identifier, start_date, end_date)
+      fetch_paginated_data(
+        endpoint: "/structures/divrec/divrecday/",
+        query: query
+      ) do |data|
+        Parser.parse_diversion_records(data, type: :day)
+      end
+    end
+
+    # Fetches monthly diversion records.
+    #
+    # @param [String, Array<String>] wdid WDID code(s)
+    # @param [String] wc_identifier Water class identifier
+    # @param [Date, nil] start_date Start date for records
+    # @param [Date, nil] end_date End date for records
+    # @return [Array<Models::DiversionRecord>] Array of monthly diversion records
+    def fetch_diversion_records_month(wdid:, wc_identifier:, start_date:, end_date:)
+      query = build_diversion_query(wdid, wc_identifier, start_date, end_date)
+      fetch_paginated_data(
+        endpoint: "/structures/divrec/divrecmonth/",
+        query: query
+      ) do |data|
+        Parser.parse_diversion_records(data, type: :month)
+      end
+    end
+
+    # Fetches yearly diversion records.
+    #
+    # @param [String, Array<String>] wdid WDID code(s)
+    # @param [String] wc_identifier Water class identifier
+    # @param [Date, nil] start_date Start date for records
+    # @param [Date, nil] end_date End date for records
+    # @return [Array<Models::DiversionRecord>] Array of yearly diversion records
+    def fetch_diversion_records_year(wdid:, wc_identifier:, start_date:, end_date:)
+      query = build_diversion_query(wdid, wc_identifier, start_date, end_date)
+      fetch_paginated_data(
+        endpoint: "/structures/divrec/divrecyear/",
+        query: query
+      ) do |data|
+        Parser.parse_diversion_records(data, type: :year)
+      end
+    end
+
+    # Builds a query for diversion record requests.
+    #
+    # @param [String, Array<String>] wdid WDID code(s)
+    # @param [String] wc_identifier Water class identifier
+    # @param [Date, nil] start_date Start date for records
+    # @param [Date, nil] end_date End date for records
+    # @return [Hash] Query parameters for the API request
+    def build_diversion_query(wdid, wc_identifier, start_date, end_date)
+      build_query({
+                    wdid: Array(wdid).join("%2C+"),
+                    wcIdentifier: format_wc_identifier(wc_identifier),
+                    "min-dataMeasDate": format_date(start_date),
+                    "max-dataMeasDate": format_date(end_date)
+                  })
+    end
+  end
+end