usgs-ruby 1.0.0

data/lib/usgs/statistics.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Usgs
+  module Statistics
+    # Fetch statistics from USGS NWIS
+    #
+    # @param sites [String, Array<String>] USGS site ID(s)
+    # @param parameter_cd [Symbol, String, Array] e.g. :discharge
+    # @param report_type [Symbol] :daily, :monthly, or :annual (default: :daily)
+    # @param stat_year_type [String, nil] "water", "calendar", "all" — only for :annual
+    #
+    # @return [Array<Usgs::Models::Statistic>]
+    #
+    # @example
+    #   Usgs.client.get_stats(sites: "06754000", report_type: :daily)
+    #   Usgs.client.get_stats(sites: "06754000", report_type: :monthly, parameter_cd: :discharge)
+    #   Usgs.client.get_stats(sites: "06754000", report_type: :annual, stat_year_type: "water")
+    #
+    def get_stats(sites:, parameter_cd: nil, report_type: :daily, stat_year_type: nil)
+      site_list   = Array(sites).join(",")
+      param_list  = resolve_parameter_codes(parameter_cd)
+      type_str    = report_type.to_s
+
+      raise ArgumentError, "report_type must be :daily, :monthly, or :annual" unless %w[daily monthly annual].include?(type_str)
+
+      raise ArgumentError, "stat_year_type is only valid when report_type: :annual" if type_str != "annual" && stat_year_type
+
+      query = {
+        format: "rdb,1.0",
+        sites: site_list,
+        parameterCd: param_list,
+        statReportType: type_str,
+        statTypeCd: "all"
+      }
+
+      query[:statYearType] = stat_year_type if stat_year_type
+
+      raw = api_get("/stat/", query)
+      Parser.parse_statistics(raw.body).map { |row| Models::Statistic.new(row) }
+    end
+  end
+end

data/lib/usgs/utils.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Usgs
+  # 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
+    # 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 do |c|
+        if c.is_a?(Symbol)
+          mapped = mapping[c]
+          if mapped.nil?
+            raise ArgumentError,
+                  "Invalid parameter code: #{c}. Valid codes are: #{mapping.keys.join(', ')}"
+          end
+
+          mapped
+        else
+          c.to_s
+        end
+      end.join(",")
+    end
+
+    def format_date(date)
+      Date.parse(date.to_s).strftime("%Y-%m-%d")
+    rescue StandardError
+      Date.today.strftime("%Y-%m-%d")
+    end
+
+    def format_datetime(datetime)
+      return nil unless datetime
+
+      Time.parse(datetime.to_s).utc.strftime("%Y-%m-%dT%H:%M")
+    end
+  end
+end

data/lib/usgs/version.rb

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

data/lib/usgs.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+require "dry-configurable"
+require "httparty"
+require "json"
+
+module Usgs
+  @loader = Zeitwerk::Loader.for_gem
+  @loader.enable_reloading
+  @loader.setup
+
+  extend Dry::Configurable
+
+  setting :user_agent, default: -> { "Usgs Ruby Gem/#{VERSION}" }
+  setting :timeout, default: 30
+  setting :base_url, default: "https://waterservices.usgs.gov/nwis"
+  setting :default_parameter, default: "DISCHRG"
+  setting :debug, default: false
+
+  class << self
+    attr_reader :loader
+
+    def client(**options)
+      Usgs::Client.new(**options)
+    end
+  end
+end

data/sig/usgs/ruby.rbs

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

data/usgs-ruby.gemspec

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "lib/usgs/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "usgs-ruby"
+  spec.version       = Usgs::VERSION
+  spec.authors       = ["Matt Michnal"]
+  spec.email         = ["mattm3646@gmail.com"]
+
+  spec.summary       = "A modern, clean Ruby client for USGS Water Services API"
+  spec.description   = "A lightweight, dependency-free Ruby gem for accessing USGS NWIS API data (sites, instantaneous values, daily values)"
+  spec.homepage      = "https://github.com/mgm702/usgs-ruby"
+  spec.license       = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata = {
+    "allowed_push_host" => "https://rubygems.org",
+    "homepage_uri" => spec.homepage,
+    "source_code_uri" => "https://github.com/mgm702/usgs-ruby",
+    "changelog_uri" => "https://github.com/mgm702/usgs-ruby/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://mgm702.com/usgs-ruby/",
+    "rubygems_mfa_required" => "true"
+  }
+
+  # Specify which files should be included
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "dry-configurable", "~> 1.0"
+  spec.add_dependency "httparty", "~> 0.21.0"
+  spec.add_dependency "zeitwerk", "~> 2.6"
+
+  # Development dependencies
+  spec.add_development_dependency "bundler", "~> 2.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "minitest-reporters", "~> 1.5"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "vcr", "~> 6.0"
+  spec.add_development_dependency "webmock", "~> 3.18"
+end

metadata

@@ -0,0 +1,231 @@
+--- !ruby/object:Gem::Specification
+name: usgs-ruby
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Matt Michnal
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2025-12-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: dry-configurable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.21.0
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.6'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.18'
+description: A lightweight, dependency-free Ruby gem for accessing USGS NWIS API data
+  (sites, instantaneous values, daily values)
+email:
+- mattm3646@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/Usgs.html
+- docs/Usgs/Client.html
+- docs/Usgs/DailyValues.html
+- docs/Usgs/InstantaneousValues.html
+- docs/Usgs/Models.html
+- docs/Usgs/Models/Reading.html
+- docs/Usgs/Models/Site.html
+- docs/Usgs/Models/Statistic.html
+- docs/Usgs/Parser.html
+- docs/Usgs/Parsers.html
+- docs/Usgs/Parsers/RdbParser.html
+- docs/Usgs/Parsers/SiteParser.html
+- docs/Usgs/Parsers/StatisticsParser.html
+- docs/Usgs/Parsers/TimeSeriesParser.html
+- docs/Usgs/Site.html
+- docs/Usgs/Statistics.html
+- docs/Usgs/Utils.html
+- docs/_index.html
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file_list.html
+- docs/frames.html
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/top-level-namespace.html
+- lib/usgs.rb
+- lib/usgs/client.rb
+- lib/usgs/daily_values.rb
+- lib/usgs/instantaneous_values.rb
+- lib/usgs/models/reading.rb
+- lib/usgs/models/site.rb
+- lib/usgs/models/statistic.rb
+- lib/usgs/parser.rb
+- lib/usgs/parsers/rdb_parser.rb
+- lib/usgs/parsers/site_parser.rb
+- lib/usgs/parsers/statistics_parser.rb
+- lib/usgs/parsers/time_series_parser.rb
+- lib/usgs/site.rb
+- lib/usgs/statistics.rb
+- lib/usgs/utils.rb
+- lib/usgs/version.rb
+- sig/usgs/ruby.rbs
+- usgs-ruby.gemspec
+homepage: https://github.com/mgm702/usgs-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mgm702/usgs-ruby
+  source_code_uri: https://github.com/mgm702/usgs-ruby
+  changelog_uri: https://github.com/mgm702/usgs-ruby/blob/main/CHANGELOG.md
+  documentation_uri: https://mgm702.com/usgs-ruby/
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: A modern, clean Ruby client for USGS Water Services API
+test_files: []