nws 0.2.0

data/lib/nws/point.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+module NWS
+  # Represents a geographic point and provides access to weather data for that location
+  class Point
+    # @return [Float] Latitude of the point
+    attr_reader :latitude
+
+    # @return [Float] Longitude of the point
+    attr_reader :longitude
+
+    # @return [String] NWS grid identifier (e.g., "LWX")
+    attr_reader :grid_id
+
+    # @return [Integer] X coordinate on the NWS grid
+    attr_reader :grid_x
+
+    # @return [Integer] Y coordinate on the NWS grid
+    attr_reader :grid_y
+
+    # @return [String] URL for the forecast endpoint
+    attr_reader :forecast_url
+
+    # @return [String] URL for the hourly forecast endpoint
+    attr_reader :forecast_hourly_url
+
+    # @return [String] URL for the forecast grid data endpoint
+    attr_reader :forecast_grid_data_url
+
+    # @return [String] URL for the observation stations endpoint
+    attr_reader :observation_stations_url
+
+    # @return [String] City name for the point
+    attr_reader :city
+
+    # @return [String] State abbreviation for the point
+    attr_reader :state
+
+    # @return [String] Time zone identifier (e.g., "America/New_York")
+    attr_reader :time_zone
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize a Point from API response data
+    #
+    # @param data [Hash] Parsed JSON response from the points API
+    # @param client [Client] NWS API client instance
+    def initialize(data, client:)
+      @client = client
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Fetch point data for given coordinates
+    #
+    # @param lat [Float] Latitude
+    # @param lon [Float] Longitude
+    # @param client [Client] NWS API client instance
+    # @return [Point] Point instance with location data
+    # @raise [InvalidCoordinatesError] if coordinates are invalid or outside US coverage
+    def self.fetch(lat, lon, client: NWS.client)
+      validate_coordinates(lat, lon)
+      lat_rounded = lat.round(4)
+      lon_rounded = lon.round(4)
+
+      data = client.get("/points/#{lat_rounded},#{lon_rounded}")
+      new(data, client: client)
+    end
+
+    # Get the 7-day forecast for this point
+    #
+    # @return [Forecast] Forecast data for this location
+    def forecast
+      data = @client.get_url(@forecast_url)
+      Forecast.new(data, point: self)
+    end
+
+    # Get the hourly forecast for this point
+    #
+    # @return [HourlyForecast] Hourly forecast data for this location
+    def hourly_forecast
+      data = @client.get_url(@forecast_hourly_url)
+      HourlyForecast.new(data, point: self)
+    end
+
+    # Get observation stations near this point
+    #
+    # @return [Array<Station>] Array of nearby weather stations, ordered by proximity
+    def observation_stations
+      data = @client.get_url(@observation_stations_url)
+      features = data["features"] || []
+      features.map { |f| Station.new(f, client: @client) }
+    end
+
+    # Get the nearest observation station to this point
+    #
+    # @return [Station, nil] Nearest station or nil if none found
+    def nearest_station
+      observation_stations.first
+    end
+
+    # Get current weather conditions for this point
+    #
+    # @return [Observation] Current weather observation
+    # @raise [NotFoundError] if no observation stations found
+    def current_conditions
+      station = nearest_station
+      raise NotFoundError.new("No observation stations found for this location") unless station
+      station.latest_observation
+    end
+
+    # Get a human-readable location string
+    #
+    # @return [String] Location in "City, State" format
+    def location_string
+      [city, state].compact.join(", ")
+    end
+
+    private
+
+    # Validate that coordinates are valid and within US coverage area
+    #
+    # @param lat [Float] Latitude
+    # @param lon [Float] Longitude
+    # @raise [InvalidCoordinatesError] if coordinates are invalid
+    def self.validate_coordinates(lat, lon)
+      lat = lat.to_f
+      lon = lon.to_f
+
+      unless lat.between?(-90, 90)
+        raise InvalidCoordinatesError, "Latitude must be between -90 and 90"
+      end
+
+      unless lon.between?(-180, 180)
+        raise InvalidCoordinatesError, "Longitude must be between -180 and 180"
+      end
+
+      # NWS API only covers US territories
+      unless lat.between?(18, 72) && lon.between?(-180, -65)
+        raise InvalidCoordinatesError, "Coordinates must be within US coverage area"
+      end
+    end
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON response
+    # @return [void]
+    def parse_data(data)
+      props = data["properties"] || {}
+
+      @latitude = props.dig("relativeLocation", "geometry", "coordinates", 1)
+      @longitude = props.dig("relativeLocation", "geometry", "coordinates", 0)
+      @grid_id = props["gridId"]
+      @grid_x = props["gridX"]
+      @grid_y = props["gridY"]
+      @forecast_url = props["forecast"]
+      @forecast_hourly_url = props["forecastHourly"]
+      @forecast_grid_data_url = props["forecastGridData"]
+      @observation_stations_url = props["observationStations"]
+      @city = props.dig("relativeLocation", "properties", "city")
+      @state = props.dig("relativeLocation", "properties", "state")
+      @time_zone = props["timeZone"]
+    end
+  end
+end

data/lib/nws/station.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module NWS
+  # Represents a weather observation station
+  class Station
+    # @return [String] Station identifier (e.g., "KDCA")
+    attr_reader :station_id
+
+    # @return [String] Station name
+    attr_reader :name
+
+    # @return [Float] Latitude of the station
+    attr_reader :latitude
+
+    # @return [Float] Longitude of the station
+    attr_reader :longitude
+
+    # @return [Float] Elevation in meters
+    attr_reader :elevation
+
+    # @return [String] Time zone identifier
+    attr_reader :time_zone
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize a Station from API response data
+    #
+    # @param data [Hash] Parsed JSON response from the stations API
+    # @param client [Client] NWS API client instance
+    def initialize(data, client:)
+      @client = client
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Fetch a station by its identifier
+    #
+    # @param station_id [String] Station identifier (e.g., "KDCA")
+    # @param client [Client] NWS API client instance
+    # @return [Station] Station instance
+    def self.fetch(station_id, client: NWS.client)
+      data = client.get("/stations/#{station_id}")
+      new(data, client: client)
+    end
+
+    # Get the latest weather observation from this station
+    #
+    # @return [Observation] Most recent observation
+    def latest_observation
+      data = @client.get("/stations/#{@station_id}/observations/latest")
+      Observation.new(data, station: self)
+    end
+
+    # Get recent weather observations from this station
+    #
+    # @param limit [Integer] Maximum number of observations to return
+    # @return [Array<Observation>] Array of recent observations
+    def observations(limit: 10)
+      data = @client.get("/stations/#{@station_id}/observations", params: { limit: limit })
+      features = data["features"] || []
+      features.map { |f| Observation.new(f, station: self) }
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON response
+    # @return [void]
+    def parse_data(data)
+      props = data["properties"] || {}
+      geometry = data["geometry"] || {}
+      coords = geometry["coordinates"] || []
+
+      @station_id = props["stationIdentifier"]
+      @name = props["name"]
+      @longitude = coords[0]
+      @latitude = coords[1]
+      @elevation = props.dig("elevation", "value")
+      @time_zone = props["timeZone"]
+    end
+  end
+end

data/lib/nws/version.rb

@@ -0,0 +1,3 @@
+module NWS
+  VERSION = "0.2.0"
+end

data/lib/nws.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "nws/version"
+require_relative "nws/errors"
+require_relative "nws/client"
+require_relative "nws/point"
+require_relative "nws/station"
+require_relative "nws/observation"
+require_relative "nws/forecast"
+require_relative "nws/hourly_forecast"
+require_relative "nws/alert"
+require_relative "nws/geocoder"
+
+# Ruby client library for the National Weather Service API
+#
+# Provides access to weather forecasts, current conditions, and alerts
+# for locations within the United States.
+#
+# @example Basic usage
+#   # Get forecast for a location
+#   forecast = NWS.forecast(39.7456, -97.0892)
+#   puts forecast.today
+#
+#   # Get current conditions
+#   conditions = NWS.current_conditions(39.7456, -97.0892)
+#   puts conditions.summary
+#
+#   # Get active alerts for a state
+#   alerts = NWS.alerts(state: "KS")
+#   alerts.each { |alert| puts alert.headline }
+module NWS
+  class << self
+    # @return [Client, nil] The default client instance
+    attr_accessor :default_client
+
+    # Get the default client, creating one if necessary
+    #
+    # @return [Client] The default NWS API client
+    def client
+      @default_client ||= Client.new
+    end
+
+    # Configure the NWS module
+    #
+    # @yield [self] Yields the module for configuration
+    # @return [void]
+    # @example
+    #   NWS.configure do |config|
+    #     config.default_client = NWS::Client.new(user_agent: "MyApp/1.0")
+    #   end
+    def configure
+      yield self
+    end
+
+    # Fetch point data for given coordinates
+    #
+    # @param lat [Float] Latitude
+    # @param lon [Float] Longitude
+    # @return [Point] Point instance with location data
+    # @raise [InvalidCoordinatesError] if coordinates are invalid or outside US coverage
+    def point(lat, lon)
+      Point.fetch(lat, lon, client: client)
+    end
+
+    # Get the 7-day forecast for a location
+    #
+    # @param lat [Float] Latitude
+    # @param lon [Float] Longitude
+    # @return [Forecast] Forecast data for the location
+    # @raise [InvalidCoordinatesError] if coordinates are invalid or outside US coverage
+    def forecast(lat, lon)
+      point(lat, lon).forecast
+    end
+
+    # Get the hourly forecast for a location
+    #
+    # @param lat [Float] Latitude
+    # @param lon [Float] Longitude
+    # @return [HourlyForecast] Hourly forecast data for the location
+    # @raise [InvalidCoordinatesError] if coordinates are invalid or outside US coverage
+    def hourly_forecast(lat, lon)
+      point(lat, lon).hourly_forecast
+    end
+
+    # Get current weather conditions for a location
+    #
+    # @param lat [Float] Latitude
+    # @param lon [Float] Longitude
+    # @return [Observation] Current weather observation
+    # @raise [InvalidCoordinatesError] if coordinates are invalid or outside US coverage
+    # @raise [NotFoundError] if no observation stations found nearby
+    def current_conditions(lat, lon)
+      point(lat, lon).current_conditions
+    end
+
+    # Fetch weather alerts
+    #
+    # @param state [String, nil] Two-letter state code to filter alerts
+    # @param point [Array<Float>, nil] Latitude and longitude pair [lat, lon]
+    # @param zone [String, nil] NWS zone identifier
+    # @param active [Boolean] Whether to fetch only active alerts
+    # @return [Array<Alert>] Array of Alert objects
+    def alerts(state: nil, point: nil, zone: nil, active: true)
+      Alert.fetch(state: state, point: point, zone: zone, active: active, client: client)
+    end
+  end
+end

metadata

@@ -0,0 +1,98 @@
+--- !ruby/object:Gem::Specification
+name: nws
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Jeff McFadden
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !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: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !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'
+description: A Ruby gem to access the publicly available National Weather Service
+  (USA) APIs for returning condition and forecast data.
+email:
+- ''
+executables:
+- nws
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- bin/nws
+- lib/nws.rb
+- lib/nws/alert.rb
+- lib/nws/client.rb
+- lib/nws/errors.rb
+- lib/nws/forecast.rb
+- lib/nws/geocoder.rb
+- lib/nws/hourly_forecast.rb
+- lib/nws/observation.rb
+- lib/nws/point.rb
+- lib/nws/station.rb
+- lib/nws/version.rb
+homepage: https://github.com/jeffmcfadden/nws
+licenses:
+- Unlicense
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: Ruby client for the National Weather Service API
+test_files: []