RubyGems - usgs-ruby - Versions diffs - 1.0.0 - Mend

usgs-ruby 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (57) hide show

checksums.yaml +7 -0
data/.rubocop.yml +87 -0
data/CHANGELOG.md +5 -0
data/CODE_OF_CONDUCT.md +84 -0
data/LICENSE.txt +21 -0
data/README.md +256 -0
data/Rakefile +24 -0
data/docs/Usgs/Client.html +563 -0
data/docs/Usgs/DailyValues.html +338 -0
data/docs/Usgs/InstantaneousValues.html +329 -0
data/docs/Usgs/Models/Reading.html +1124 -0
data/docs/Usgs/Models/Site.html +2030 -0
data/docs/Usgs/Models/Statistic.html +3981 -0
data/docs/Usgs/Models.html +117 -0
data/docs/Usgs/Parser.html +346 -0
data/docs/Usgs/Parsers/RdbParser.html +354 -0
data/docs/Usgs/Parsers/SiteParser.html +174 -0
data/docs/Usgs/Parsers/StatisticsParser.html +228 -0
data/docs/Usgs/Parsers/TimeSeriesParser.html +189 -0
data/docs/Usgs/Parsers.html +117 -0
data/docs/Usgs/Site.html +445 -0
data/docs/Usgs/Statistics.html +335 -0
data/docs/Usgs/Utils.html +357 -0
data/docs/Usgs.html +303 -0
data/docs/_index.html +286 -0
data/docs/class_list.html +54 -0
data/docs/css/common.css +1 -0
data/docs/css/full_list.css +58 -0
data/docs/css/style.css +503 -0
data/docs/file.README.html +111 -0
data/docs/file_list.html +59 -0
data/docs/frames.html +22 -0
data/docs/index.html +111 -0
data/docs/js/app.js +344 -0
data/docs/js/full_list.js +242 -0
data/docs/js/jquery.js +4 -0
data/docs/method_list.html +598 -0
data/docs/top-level-namespace.html +110 -0
data/lib/usgs/client.rb +62 -0
data/lib/usgs/daily_values.rb +38 -0
data/lib/usgs/instantaneous_values.rb +35 -0
data/lib/usgs/models/reading.rb +43 -0
data/lib/usgs/models/site.rb +61 -0
data/lib/usgs/models/statistic.rb +95 -0
data/lib/usgs/parser.rb +23 -0
data/lib/usgs/parsers/rdb_parser.rb +55 -0
data/lib/usgs/parsers/site_parser.rb +13 -0
data/lib/usgs/parsers/statistics_parser.rb +40 -0
data/lib/usgs/parsers/time_series_parser.rb +54 -0
data/lib/usgs/site.rb +50 -0
data/lib/usgs/statistics.rb +42 -0
data/lib/usgs/utils.rb +50 -0
data/lib/usgs/version.rb +5 -0
data/lib/usgs.rb +28 -0
data/sig/usgs/ruby.rbs +6 -0
data/usgs-ruby.gemspec +48 -0
metadata +231 -0

data/docs/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.37
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" />
+<script type="text/javascript">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Usgs.html" title="Usgs (module)">Usgs</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Mon Dec 15 21:52:18 2025 by
+  <a href="https://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.37 (ruby-3.2.2).
+</div>
+    </div>
+  </body>
+</html>

data/lib/usgs/client.rb ADDED Viewed

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+module Usgs
+  class Client
+    include DailyValues
+    include InstantaneousValues
+    include Site
+    include Statistics
+    attr_reader :timeout, :user_agent, :debug
+    def initialize(timeout: 30, user_agent: "usgs-ruby/#{Usgs::VERSION}", debug: nil)
+      @timeout    = timeout
+      @user_agent = user_agent
+      @debug      = debug.nil? ? Usgs.config.debug : debug
+    end
+    # Base URL for USGS Water Services
+    def base_url
+      "https://waterservices.usgs.gov/nwis"
+    end
+    # Public: Perform GET and return response from API
+    def api_get(path, query = {})
+      query = query.compact
+      url   = "#{base_url}#{path}"
+      fetch_url(url, query: query, timeout: timeout, user_agent: user_agent)
+    end
+    private
+    def fetch_url(url, query: {}, timeout: 30, user_agent: nil)
+      uri = URI(url)
+      uri.query = URI.encode_www_form(query).gsub("+", "%20") unless query.empty?
+      puts "\n=== USGS Request ===\n#{uri}\n====================\n" if @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)
+        raise "USGS API Error #{response.code}: #{response.message}\n#{response.body}" unless response.is_a?(Net::HTTPSuccess)
+        response
+      end
+    end
+  end
+end

data/lib/usgs/daily_values.rb ADDED Viewed

@@ -0,0 +1,38 @@
+# lib/usgs/daily_values.rb
+# frozen_string_literal: true
+module Usgs
+  module DailyValues
+    include Utils
+    # Fetch daily values (DV) from USGS NWIS
+    #
+    # @param sites [String, Array<String>] USGS site ID(s)
+    # @param parameter_cd [Symbol, String, Array] e.g. :discharge
+    # @param start_date [Date, String, nil] Start date — defaults to 10 years ago if omitted
+    # @param end_date [Date, String, nil] End date — defaults to today
+    #
+    # @return [Array<Usgs::Models::Reading>]
+    #
+    # @example Most recent year
+    #   Usgs.client.get_dv(sites: "06754000", parameter_cd: :discharge)
+    #
+    # @example Full POR
+    #   Usgs.client.get_dv(sites: "06754000", parameter_cd: :discharge, start_date: "1900-01-01")
+    #
+    def get_dv(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,
+        startDT: format_date(start_date || (Time.now.utc - (48 * 60 * 60))),
+        endDT: format_date(end_date || Time.now.utc)
+      }.compact
+      response = api_get("/dv/", query)
+      Parser.parse_time_series_values(JSON.parse(response.body))
+    end
+  end
+end

data/lib/usgs/instantaneous_values.rb ADDED Viewed

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+module Usgs
+  module InstantaneousValues
+    include Utils
+    # 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
+      response = api_get("/iv/", query)
+      Parser.parse_time_series_values(JSON.parse(response.body))
+    end
+  end
+end

data/lib/usgs/models/reading.rb ADDED Viewed

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+module Usgs
+  module Models
+    # Represents a USGS reading/measurement
+    #
+    # @!attribute [rw] site_no
+    #   @return [String] USGS site number
+    # @!attribute [rw] parameter_cd
+    #   @return [String] Parameter code
+    # @!attribute [rw] datetime
+    #   @return [String] Date and time of reading
+    # @!attribute [rw] value
+    #   @return [Float, nil] Measured value
+    # @!attribute [rw] qualifiers
+    #   @return [Array<String>] Quality/approval codes
+    # @!attribute [rw] unit
+    #   @return [String] Unit of measurement
+    # @!attribute [rw] metadata
+    #   @return [Hash] Additional metadata
+    class Reading
+      ATTRIBUTES = %i[
+        site_no
+        parameter_cd
+        datetime
+        value
+        qualifiers
+        unit
+        metadata
+      ].freeze
+      attr_accessor(*ATTRIBUTES) # :nodoc:
+      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

data/lib/usgs/models/site.rb ADDED Viewed

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+module Usgs
+  module Models
+    # Represents a USGS monitoring site/station
+    #
+    # @!attribute [rw] agency_cd
+    #   @return [String] Agency code
+    # @!attribute [rw] site_no
+    #   @return [String] USGS site number
+    # @!attribute [rw] station_nm
+    #   @return [String] Station name
+    # @!attribute [rw] site_tp_cd
+    #   @return [String] Site type code
+    # @!attribute [rw] dec_lat_va
+    #   @return [Float, nil] Decimal latitude
+    # @!attribute [rw] dec_long_va
+    #   @return [Float, nil] Decimal longitude
+    # @!attribute [rw] coord_acy_cd
+    #   @return [String] Coordinate accuracy code
+    # @!attribute [rw] dec_coord_datum_cd
+    #   @return [String] Decimal coordinate datum code
+    # @!attribute [rw] alt_va
+    #   @return [String] Altitude value
+    # @!attribute [rw] alt_acy_va
+    #   @return [String] Altitude accuracy value
+    # @!attribute [rw] alt_datum_cd
+    #   @return [String] Altitude datum code
+    # @!attribute [rw] huc_cd
+    #   @return [String] Hydrologic unit code
+    # @!attribute [rw] metadata
+    #   @return [Hash] Additional metadata
+    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) # :nodoc:
+      def initialize(attrs = {})
+        attrs = {} unless attrs.is_a?(Hash)
+        attrs[:metadata] ||= {}
+        ATTRIBUTES.each do |attr|
+          instance_variable_set(:"@#{attr}", attrs[attr]) if attrs.key?(attr)
+        end
+      end
+    end
+  end
+end

data/lib/usgs/models/statistic.rb ADDED Viewed

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+module Usgs
+  module Models
+    # Represents a USGS statistic record
+    #
+    # @!attribute [rw] site_no
+    #   @return [String] USGS site number
+    # @!attribute [rw] parameter_cd
+    #   @return [String] Parameter code
+    # @!attribute [rw] month_nu
+    #   @return [Float, nil] Month number
+    # @!attribute [rw] day_nu
+    #   @return [Float, nil] Day number
+    # @!attribute [rw] begin_yr
+    #   @return [Float, nil] Beginning year
+    # @!attribute [rw] end_yr
+    #   @return [Float, nil] Ending year
+    # @!attribute [rw] count_nu
+    #   @return [Float, nil] Count of values
+    # @!attribute [rw] mean_va
+    #   @return [Float, nil] Mean value
+    # @!attribute [rw] max_va
+    #   @return [Float, nil] Maximum value
+    # @!attribute [rw] max_va_yr
+    #   @return [Float, nil] Year of maximum value
+    # @!attribute [rw] min_va
+    #   @return [Float, nil] Minimum value
+    # @!attribute [rw] min_va_yr
+    #   @return [Float, nil] Year of minimum value
+    # @!attribute [rw] p05_va
+    #   @return [Float, nil] 5th percentile value
+    # @!attribute [rw] p10_va
+    #   @return [Float, nil] 10th percentile value
+    # @!attribute [rw] p20_va
+    #   @return [Float, nil] 20th percentile value
+    # @!attribute [rw] p25_va
+    #   @return [Float, nil] 25th percentile value
+    # @!attribute [rw] p50_va
+    #   @return [Float, nil] 50th percentile (median) value
+    # @!attribute [rw] p75_va
+    #   @return [Float, nil] 75th percentile value
+    # @!attribute [rw] p80_va
+    #   @return [Float, nil] 80th percentile value
+    # @!attribute [rw] p90_va
+    #   @return [Float, nil] 90th percentile value
+    # @!attribute [rw] p95_va
+    #   @return [Float, nil] 95th percentile value
+    # @!attribute [rw] metadata
+    #   @return [Hash] Additional metadata
+    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) # :nodoc:
+      def initialize(data = {})
+        data[:metadata] ||= {}
+        attrs = data.is_a?(Hash) ? data : {}
+        ATTRIBUTES.each do |attr|
+          value = attrs[attr]
+          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

data/lib/usgs/parser.rb ADDED Viewed

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+module Usgs
+  class Parser
+    class << self
+      def parse_sites(response)
+        Parsers::RdbParser.parse(response)
+      end
+      def parse_time_series(response, timescale: :instantaneous)
+        # Parsers::TimeSeriesParser.parse(response, timescale: timescale)
+      end
+      def parse_time_series_values(response)
+        Parsers::TimeSeriesParser.parse(response)
+      end
+      def parse_statistics(response)
+        Parsers::StatisticsParser.parse(response)
+      end
+    end
+  end
+end

data/lib/usgs/parsers/rdb_parser.rb ADDED Viewed

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+module Usgs
+  module Parsers
+    module RdbParser
+      class << self
+        # Parse any USGS RDB response (format=rdb or rdb,1.0)
+        #
+        # @param text [String] Raw RDB text
+        # @return [Array<Hash>] Rows with symbolized column names
+        def parse(text)
+          lines = text.lines.map(&:rstrip)
+          # Drop all comment lines (#)
+          data_lines = lines.drop_while { |l| l.start_with?("#") }
+          return [] if data_lines.empty?
+          field_names_line = data_lines[0]
+          data_start_index = if data_lines[1]&.match?(/\A(\d+[sd])\t/)
+                               2
+                             else
+                               1
+                             end
+          column_names = field_names_line.split("\t")
+          data_lines[data_start_index..].map do |line|
+            next if line.empty? || line.start_with?("#")
+            values = line.split("\t")
+            column_names.zip(values).to_h.transform_keys { |k| k.strip.to_sym }
+          end.compact
+        end
+        # For time series (iv, dv, etc.)
+        def parse_time_series(text)
+          rows = parse(text)
+          rows.map do |row|
+            value = row[:value]&.strip
+            value = nil if value.nil? || value == "" || value == "-999999" || value.downcase.include?("ice")
+            {
+              site_no: row[:site_no]&.strip,
+              datetime: row[:datetime] || row[:dateTime],
+              value: value&.to_f,
+              code: row[:value_cd] || row[:qualifiers],
+              parameter_cd: row[:parameter_cd] || row[:parm_cd]
+            }.compact
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usgs/parsers/site_parser.rb ADDED Viewed

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+module Usgs
+  module Parsers
+    module SiteParser
+      class << self
+        def parse_sites(response)
+          response
+        end
+      end
+    end
+  end
+end

data/lib/usgs/parsers/statistics_parser.rb ADDED Viewed

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+module Usgs
+  module Parsers
+    module StatisticsParser
+      class << self
+        def parse(rdb_text)
+          rows = Parsers::RdbParser.parse(rdb_text)
+          rows.map do |row|
+            {
+              site_no: row[:site_no]&.strip,
+              parameter_cd: row[:parameter_cd]&.strip,
+              month_nu: row[:month_nu]&.to_i,
+              day_nu: row[:day_nu]&.to_i,
+              begin_yr: row[:begin_yr]&.to_i,
+              end_yr: row[:end_yr]&.to_i,
+              count_nu: row[:count_nu]&.to_i,
+              mean_va: row[:mean_va],
+              max_va: row[:max_va],
+              max_va_yr: row[:max_va_yr]&.to_i,
+              min_va: row[:min_va],
+              min_va_yr: row[:min_va_yr]&.to_i,
+              p05_va: row[:p05_va],
+              p10_va: row[:p10_va],
+              p20_va: row[:p20_va],
+              p25_va: row[:p25_va],
+              p50_va: row[:p50_va],
+              p75_va: row[:p75_va],
+              p80_va: row[:p80_va],
+              p90_va: row[:p90_va],
+              p95_va: row[:p95_va],
+              metadata: {}
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usgs/parsers/time_series_parser.rb ADDED Viewed

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+module Usgs
+  module Parsers
+    module TimeSeriesParser
+      class << self
+        # Parse both Instantaneous Values (IV) and Daily Values (DV)
+        # They have identical JSON structure
+        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", "Bkw", "Rat"
+                      nil
+                    else
+                      raw_value.to_f
+                    end
+            # For DV: "2025-12-04T00:00:00.000" → "2025-12-04"
+            # For IV: "2025-12-04T12:15:00.000-07:00" → full string (preserved)
+            datetime = v["dateTime"]
+            datetime = datetime[0..9] if datetime&.include?("T00:00:00.000")
+            {
+              site_no: site_no,
+              parameter_cd: parameter_cd,
+              datetime: datetime,
+              value: value,
+              qualifiers: v["qualifiers"],
+              unit: unit,
+              metadata: {}
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/usgs/site.rb ADDED Viewed

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+module Usgs
+  module Site
+    include Utils
+    # Fetch USGS monitoring locations (sites)
+    #
+    # @param state_cd [String] Two-letter state code (e.g., "CO")
+    # @param county_cd [String] FIPS county code (e.g., "08013")
+    # @param huc [String] 2-16 digit Hydrologic Unit Code
+    # @param bBox [String] "west,south,east,north" in decimal degrees
+    # @param site_name [String] Text search in station name
+    # @param site_type [String] e.g., "ST" (stream), "GW", "LK", "WE"
+    # @param site_status [String] "active", "inactive", "all" (default: "all")
+    # @param parameter_cd [String, Symbol, Array] e.g. :discharge, "00060", or [:discharge, :gage_height]
+    #
+    # @return [Array<Usgs::Models::Site>]
+    # @raise [ArgumentError] if no major filter is provided
+    #
+    # @example
+    #   Usgs.client.get_sites(state_cd: "CO", parameter_cd: :discharge)
+    #
+    def get_sites(state_cd: nil, county_cd: nil, huc: nil, b_box: nil, site_name: nil,
+                  site_type: nil, site_status: "all", parameter_cd: nil)
+      query = {
+        format: "rdb,1.0",
+        stateCd: state_cd,
+        countyCd: county_cd,
+        huc: huc,
+        bBox: b_box,
+        siteName: site_name,
+        siteType: site_type,
+        siteStatus: site_status
+      }.compact
+      if parameter_cd
+        resolved = resolve_parameter_codes(parameter_cd)
+        query[:parameterCd] = resolved if resolved && !resolved.empty?
+      end
+      # Validate for at least one major filter
+      major_keys = %i[stateCd countyCd huc bBox].map(&:to_sym)
+      raise ArgumentError, "You must provide at least one major filter: state_cd, county_cd, huc or b_box" if (query.keys & major_keys).empty?
+      raw = api_get("/site/", query)
+      Parser.parse_sites(raw.body).map { |row| Models::Site.new(row) }
+    end
+  end
+end