Merge pull request #1 from mgm702/develop

Instant Values, Sites and Statistics added to gem from USGS API

Author: mgm702

bin/console

@@ -2,7 +2,7 @@
 # frozen_string_literal: true
 
 require "bundler/setup"
-require "usgs/ruby"
+require "usgs"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.

lib/usgs/client.rb

@@ -1,60 +1,65 @@
 # frozen_string_literal: true
+require 'pry'
 
 module Usgs
-  # Main client class for interacting with USGS Water Services API
-  #
-  # @example Basic usage
-  #   Usgs.client.get_sites(state_cd: "CO")
-  #
-  # @example With custom timeout
-  #   client = Usgs::Client.new(timeout: 60)
   class Client
-    include HTTParty
-    base_uri Usgs.config.base_url
-
     include Site
     include InstantaneousValues
-    include DailyValues
+    include Statistics
 
     attr_reader :timeout, :user_agent
 
-    # Initialize a new USGS client
-    #
-    # @param timeout [Integer] Request timeout in seconds (default: 30)
-    # @param user_agent [String] Custom User-Agent header
-    def initialize(timeout: 30, user_agent: "usgs-ruby/#{Usgs::VERSION}")
-      @timeout     = timeout
-      @user_agent  = user_agent
+    def initialize(timeout: 30, user_agent: "usgs-ruby/#{Usgs::VERSION}", debug: false)
+      @timeout    = timeout
+      @user_agent = user_agent
+      @debug = debug
+    end
+
+    # Base URL for USGS Water Services
+    def base_url
+      "https://waterservices.usgs.gov/nwis"
     end
 
-    # Perform a GET request and parse JSON response
-    #
-    # @param path [String] API endpoint path
-    # @param query [Hash] Query parameters
-    # @return [Hash] Parsed JSON response
-    def get_json(path, query = {})
+    # Public: Perform GET and return parsed JSON
+    def api_get(path, query = {})
       query = query.compact
       url   = "#{base_url}#{path}"
 
-      response = fetch_url(url, query: query, timeout: timeout, user_agent: user_agent)
-      JSON.parse(response.body)
+      # binding.pry
+      fetch_url(url, query: query, timeout: timeout, user_agent: user_agent)
     end
 
     private
 
-    # Low-level fetch with debug support
-    #
-    # @private
     def fetch_url(url, query: {}, timeout: 30, user_agent: nil)
-      uri = build_uri(url, query)
+      uri = URI(url)
+      uri.query = URI.encode_www_form(query) unless query.empty?
 
-      if Usgs.instance_variable_defined?(:@debug) && Usgs.instance_variable_get(:@debug)
-        puts "\n=== USGS API Request ==="
-        puts "URL: #{uri}"
-        puts "=======================\n"
-      end
+      puts "\n=== USGS Request ===\n#{uri}\n====================\n" if $DEBUG || ENV["USGS_DEBUG"]
 
       http_get(uri, timeout: timeout, user_agent: user_agent)
     end
+
+    def http_get(uri, timeout: 30, user_agent: nil)
+      Net::HTTP.start(
+        uri.host,
+        uri.port,
+        use_ssl: true,
+        open_timeout: timeout,
+        read_timeout: timeout
+      ) do |http|
+        request = Net::HTTP::Get.new(uri)
+        request["User-Agent"] = user_agent if user_agent
+        request["Accept"]     = "application/json"
+
+        response = http.request(request)
+
+        if response.is_a?(Net::HTTPSuccess)
+          response
+        else
+          raise "USGS API Error #{response.code}: #{response.message}\n#{response.body}"
+        end
+      end
+    end
   end
 end

lib/usgs/instantaneous_values.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Usgs
+  module InstantaneousValues
+    # Fetch instantaneous values (IV) from USGS NWIS
+    #
+    # @param sites [String, Array<String>] One or more USGS site IDs
+    # @param parameter_cd [Symbol, String, Array] e.g. :discharge, "00060", or [:discharge, :gage_height]
+    # @param start_date [DateTime, Date, Time, String, nil] Start time
+    # @param end_date [DateTime, Date, Time, String, nil] End time (default: now)
+    #
+    # @return [Array<Usgs::Models::Reading>]
+    #
+    # @example
+    #   Usgs.client.get_iv(sites: "06754000", parameter_cd: :discharge, start_date: 1.day.ago)
+    #
+    def get_iv(sites:, parameter_cd: nil, start_date: nil, end_date: nil)
+      site_list = Array(sites).join(",")
+      param_list = resolve_parameter_codes(parameter_cd)
+
+      query = {
+        format: "json",
+        sites: site_list,
+        parameterCd: param_list,
+        # Default to the the last 24hrs if not filled out
+        startDT: format_datetime(start_date || (Time.now.utc - (24 * 60 * 60))),
+        endDT: format_datetime(end_date || Time.now.utc)
+      }.compact
+
+      binding.pry
+      response = api_get("/iv/", query)
+      Parser.parse_instantaneous_values(JSON.parse(response.body))
+    end
+
+    private
+
+    # Convert symbols to official USGS parameter codes
+    def resolve_parameter_codes(codes)
+      return nil if codes.nil?
+
+      mapping = {
+        discharge:      "00060",
+        gage_height:    "00065",
+        temperature:    "00010",
+        precipitation:  "00045",
+        do:             "00300",
+        conductivity:   "00095",
+        ph:             "00400"
+      }
+
+      Array(codes).map { |c| mapping[c.to_sym] || c.to_s }.join(",")
+    end
+
+    def format_datetime(dt)
+      return nil unless dt
+      Time.parse(dt.to_s).utc.strftime("%Y-%m-%dT%H:%M")
+    end
+  end
+end

lib/usgs/models/reading.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Usgs
+  module Models
+    class Reading
+      ATTRIBUTES = %i[
+        site_no
+        parameter_cd
+        datetime
+        value
+        qualifiers
+        unit
+        metadata
+      ].freeze
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(data = {})
+        data[:metadata] ||= {}
+        attrs = data.is_a?(Hash) ? data : {}
+
+        ATTRIBUTES.each do |attr|
+          instance_variable_set(:"@#{attr}", attrs[attr]) if attrs.key?(attr)
+        end
+      end
+    end
+  end
+end

lib/usgs/models/site.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Usgs
+  module Models
+    class Site
+      ATTRIBUTES = %i[
+        agency_cd
+        site_no
+        station_nm
+        site_tp_cd
+        dec_lat_va
+        dec_long_va
+        coord_acy_cd
+        dec_coord_datum_cd
+        alt_va
+        alt_acy_va
+        alt_datum_cd
+        huc_cd
+        metadata
+      ].freeze
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(attrs = {})
+        # Accept either a single hash OR keyword arguments
+        attrs = attrs.is_a?(Hash) ? attrs : {}
+        attrs[:metadata] ||= {}
+
+        ATTRIBUTES.each do |attr|
+          instance_variable_set(:"@#{attr}", attrs[attr]) if attrs.key?(attr)
+        end
+      end
+    end
+  end
+end

lib/usgs/models/statistic.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Usgs
+  module Models
+    class Statistic
+      ATTRIBUTES = %i[
+        site_no
+        parameter_cd
+        month_nu
+        day_nu
+        begin_yr
+        end_yr
+        count_nu
+        mean_va
+        max_va
+        max_va_yr
+        min_va
+        min_va_yr
+        p05_va
+        p10_va
+        p20_va
+        p25_va
+        p50_va
+        p75_va
+        p80_va
+        p90_va
+        p95_va
+        metadata
+      ].freeze
+
+      attr_accessor(*ATTRIBUTES)
+
+      def initialize(data = {})
+        data[:metadata] ||= {}
+        attrs = data.is_a?(Hash) ? data : {}
+
+        ATTRIBUTES.each do |attr|
+          value = attrs[attr]
+
+          # Convert all the _va fields (values) from string to float
+          if value.is_a?(String) && attr.to_s.end_with?("_va", "_yr", "_nu")
+            stripped = value.strip
+            value = stripped.empty? || stripped == "." ? nil : stripped.to_f
+          end
+
+          instance_variable_set(:"@#{attr}", value) if attrs.key?(attr)
+        end
+      end
+    end
+  end
+end

lib/usgs/parser.rb

@@ -4,12 +4,20 @@ module Usgs
   class Parser
     class << self
       def parse_sites(response)
-        Parsers::SiteParser.parse_sites(response)
+        Parsers::RdbParser.parse(response)
       end
 
       def parse_time_series(response, timescale: :instantaneous)
         # Parsers::TimeSeriesParser.parse(response, timescale: timescale)
       end
+
+      def parse_instantaneous_values(response)
+        Parsers::InstantaneousValuesParser.parse(response)
+      end
+
+      def parse_statistics(response)
+        Parsers::StatisticsParser.parse(response)
+      end
     end
   end
 end

lib/usgs/parsers.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Usgs
+  module Parsers
+    module InstantaneousValuesParser
+      class << self
+        def parse(response)
+          series_list = response.dig("value", "timeSeries") || []
+          series_list.flat_map { |series| parse_series(series) }
+        end
+
+        private
+
+        def parse_series(series)
+          info     = series["sourceInfo"]
+          variable = series["variable"]
+          values   = series["values"]&.first&.dig("value") || []
+
+          site_no      = info.dig("siteCode", 0, "value")
+          parameter_cd = variable.dig("variableCode", 0, "value")
+          unit         = variable.dig("unit", "unitCode")
+
+          values.map do |v|
+            raw_value = v["value"]
+
+            value = case raw_value
+                    when nil, "", "-999999", "Ice", "Eqp", "Fld"
+                      nil
+                    else
+                      raw_value.to_f
+                    end
+
+            {
+              site_no:      site_no,
+              parameter_cd: parameter_cd,
+              datetime:     v["dateTime"],
+              value:        value,
+              qualifiers:   v["qualifiers"],
+              unit:         unit,
+              metadata:     {}
+            }
+          end
+        end
+      end
+    end
+  end
+end