nws 0.2.0

data/lib/nws/geocoder.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require "fileutils"
+
+module NWS
+  # Geocoder for converting location names to coordinates using OpenStreetMap Nominatim
+  #
+  # Implements rate limiting (1 request/second) and caching (7-day TTL) to comply
+  # with Nominatim usage policy.
+  #
+  # @example
+  #   geocoder = NWS::Geocoder.new
+  #   result = geocoder.geocode("Denver, CO")
+  #   puts result.latitude  # => 39.7392
+  #   puts result.longitude # => -104.9903
+  class Geocoder
+    # @return [String] Nominatim API endpoint URL
+    NOMINATIM_URL = "https://nominatim.openstreetmap.org/search"
+
+    # @return [Float] Minimum seconds between API requests
+    MIN_REQUEST_INTERVAL = 1.0
+
+    # @return [Integer] Cache time-to-live in seconds (7 days)
+    CACHE_TTL = 86400 * 7
+
+    # @return [String] Attribution text required by ODbL license
+    ATTRIBUTION = "Geocoding data © OpenStreetMap contributors (ODbL)".freeze
+
+    @last_request_time = nil
+    @cache = {}
+
+    class << self
+      # @return [Time, nil] Timestamp of the last API request
+      attr_accessor :last_request_time
+
+      # @return [Hash] In-memory cache storage
+      attr_accessor :cache
+
+      # Enforce rate limiting by sleeping if necessary
+      #
+      # Ensures at least MIN_REQUEST_INTERVAL seconds between API requests
+      # to comply with Nominatim usage policy.
+      #
+      # @return [void]
+      def rate_limit!
+        if last_request_time
+          elapsed = Time.now - last_request_time
+          if elapsed < MIN_REQUEST_INTERVAL
+            sleep(MIN_REQUEST_INTERVAL - elapsed)
+          end
+        end
+        self.last_request_time = Time.now
+      end
+
+      # Get the cache directory path
+      #
+      # @return [String] Path to the cache directory (~/.cache/nws by default)
+      def cache_dir
+        @cache_dir ||= File.join(Dir.home, ".cache", "nws")
+      end
+
+      # Set the cache directory path
+      #
+      # @param dir [String] New cache directory path
+      # @return [String] The new cache directory path
+      def cache_dir=(dir)
+        @cache_dir = dir
+      end
+
+      # Ensure the cache directory exists
+      #
+      # @return [void]
+      def ensure_cache_dir
+        FileUtils.mkdir_p(cache_dir) unless File.directory?(cache_dir)
+      end
+
+      # Generate the cache file path for a query
+      #
+      # @param query [String] The geocoding query
+      # @return [String] Path to the cache file for this query
+      def cache_path(query)
+        safe_name = query.downcase.gsub(/[^a-z0-9]+/, "_")[0..50]
+        File.join(cache_dir, "geocode_#{safe_name}.json")
+      end
+
+      # Read a cached geocoding result
+      #
+      # @param query [String] The geocoding query
+      # @return [Hash, nil] Cached result data or nil if not found or expired
+      def read_cache(query)
+        path = cache_path(query)
+        return nil unless File.exist?(path)
+
+        data = JSON.parse(File.read(path))
+        cached_at = Time.parse(data["cached_at"])
+
+        if Time.now - cached_at > CACHE_TTL
+          File.delete(path) rescue nil
+          return nil
+        end
+
+        data["result"]
+      rescue JSON::ParserError, ArgumentError
+        File.delete(path) rescue nil
+        nil
+      end
+
+      # Write a geocoding result to the cache
+      #
+      # @param query [String] The geocoding query
+      # @param result [GeocodingResult] The result to cache
+      # @return [void]
+      def write_cache(query, result)
+        ensure_cache_dir
+        path = cache_path(query)
+        data = {
+          "cached_at" => Time.now.iso8601,
+          "query" => query,
+          "result" => {
+            "latitude" => result.latitude,
+            "longitude" => result.longitude,
+            "display_name" => result.display_name,
+            "place_type" => result.place_type
+          }
+        }
+        File.write(path, JSON.pretty_generate(data))
+      rescue StandardError
+        # Ignore cache write failures
+      end
+
+      # Get the required attribution text
+      #
+      # @return [String] Attribution text for OpenStreetMap/ODbL
+      def attribution
+        ATTRIBUTION
+      end
+    end
+
+    # Initialize a new Geocoder instance
+    #
+    # @param user_agent [String, nil] User-Agent header for API requests
+    def initialize(user_agent: nil)
+      @user_agent = user_agent || "(nws-ruby-gem, #{NWS::VERSION})"
+    end
+
+    # Geocode a location query to coordinates
+    #
+    # @param query [String] Location name or address to geocode
+    # @return [GeocodingResult] Result containing coordinates and metadata
+    # @raise [APIError] if the API request fails
+    # @raise [NotFoundError] if no results are found for the query
+    def geocode(query)
+      # Check cache first
+      if (cached = self.class.read_cache(query))
+        return GeocodingResult.new(
+          latitude: cached["latitude"],
+          longitude: cached["longitude"],
+          display_name: cached["display_name"],
+          place_type: cached["place_type"],
+          from_cache: true
+        )
+      end
+
+      # Rate limit before making request
+      self.class.rate_limit!
+
+      uri = URI.parse(NOMINATIM_URL)
+      uri.query = URI.encode_www_form(format: "json", q: query, limit: 1)
+
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = @user_agent
+      request["Accept"] = "application/json"
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = true
+      http.open_timeout = 10
+      http.read_timeout = 30
+
+      response = http.request(request)
+
+      unless response.code.to_i == 200
+        raise APIError.new("Geocoding failed: #{response.code}", status_code: response.code.to_i)
+      end
+
+      results = JSON.parse(response.body)
+
+      if results.empty?
+        raise NotFoundError.new("Location not found: #{query}")
+      end
+
+      result_data = results.first
+      lat = result_data["lat"].to_f.round(4)
+      lon = result_data["lon"].to_f.round(4)
+
+      result = GeocodingResult.new(
+        latitude: lat,
+        longitude: lon,
+        display_name: result_data["display_name"],
+        place_type: result_data["type"],
+        from_cache: false
+      )
+
+      # Cache the result
+      self.class.write_cache(query, result)
+
+      result
+    end
+  end
+
+  # Represents a geocoding result with coordinates and metadata
+  class GeocodingResult
+    # @return [Float] Latitude of the location
+    attr_reader :latitude
+
+    # @return [Float] Longitude of the location
+    attr_reader :longitude
+
+    # @return [String] Full display name of the location
+    attr_reader :display_name
+
+    # @return [String] Type of place (e.g., "city", "administrative")
+    attr_reader :place_type
+
+    # @return [Boolean] Whether this result was retrieved from cache
+    attr_reader :from_cache
+
+    # @return [String] Attribution text required by ODbL license
+    ATTRIBUTION = Geocoder::ATTRIBUTION
+
+    # Initialize a new GeocodingResult
+    #
+    # @param latitude [Float] Latitude of the location
+    # @param longitude [Float] Longitude of the location
+    # @param display_name [String] Full display name of the location
+    # @param place_type [String] Type of place
+    # @param from_cache [Boolean] Whether this result was retrieved from cache
+    def initialize(latitude:, longitude:, display_name:, place_type:, from_cache: false)
+      @latitude = latitude
+      @longitude = longitude
+      @display_name = display_name
+      @place_type = place_type
+      @from_cache = from_cache
+    end
+
+    # Check if this result was retrieved from cache
+    #
+    # @return [Boolean] True if from cache
+    def from_cache?
+      @from_cache
+    end
+
+    # Convert to array of [latitude, longitude]
+    #
+    # @return [Array<Float>] Coordinate pair as [latitude, longitude]
+    def to_a
+      [latitude, longitude]
+    end
+
+    # Get a formatted string representation
+    #
+    # @return [String] Coordinates and display name
+    def to_s
+      "#{latitude}, #{longitude} (#{display_name})"
+    end
+
+    # Get the required attribution text
+    #
+    # @return [String] Attribution text for OpenStreetMap/ODbL
+    def attribution
+      ATTRIBUTION
+    end
+  end
+end

data/lib/nws/hourly_forecast.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module NWS
+  # Represents an hourly weather forecast
+  class HourlyForecast
+    # @return [Point, nil] The point this forecast is for
+    attr_reader :point
+
+    # @return [Time, nil] When the forecast was last updated
+    attr_reader :updated_at
+
+    # @return [Array<HourlyPeriod>] Hourly forecast periods
+    attr_reader :periods
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize an HourlyForecast from API response data
+    #
+    # @param data [Hash] Parsed JSON response from the hourly forecast API
+    # @param point [Point, nil] The point this forecast is for
+    def initialize(data, point: nil)
+      @point = point
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Get the next N hours of forecast data
+    #
+    # @param count [Integer] Number of hours to return (default: 24)
+    # @return [Array<HourlyPeriod>] Array of hourly periods
+    def next_hours(count = 24)
+      @periods.first(count)
+    end
+
+    # Group forecast periods by day
+    #
+    # @return [Hash{String => Array<HourlyPeriod>}] Periods grouped by date (YYYY-MM-DD)
+    def by_day
+      @periods.group_by { |p| p.start_time.strftime("%Y-%m-%d") }
+    end
+
+    # Get a formatted string representation of the hourly forecast
+    #
+    # @param hours [Integer] Number of hours to display (default: 24)
+    # @return [String] Multi-line formatted hourly forecast
+    def to_s(hours: 24)
+      lines = []
+      lines << "Hourly Forecast for #{point&.location_string || 'Unknown Location'}"
+      lines << "Updated: #{updated_at&.strftime('%Y-%m-%d %I:%M %p')}"
+      lines << ""
+
+      by_day.each do |date, periods|
+        lines << date_label(periods.first.start_time)
+
+        periods.first(hours).each do |period|
+          time_str = period.start_time.strftime("%-l%P")
+          lines << "  #{time_str.rjust(4)}: #{period.temperature}°#{period.temperature_unit} - #{period.short_forecast}"
+          hours -= 1
+          break if hours <= 0
+        end
+
+        lines << ""
+        break if hours <= 0
+      end
+
+      lines.join("\n")
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON response
+    # @return [void]
+    def parse_data(data)
+      props = data["properties"] || {}
+      @updated_at = parse_time(props["updateTime"])
+
+      raw_periods = props["periods"] || []
+      @periods = raw_periods.map { |p| HourlyPeriod.new(p) }
+    end
+
+    # Parse an ISO8601 time string
+    #
+    # @param str [String, nil] Time string
+    # @return [Time, nil] Parsed time or nil
+    def parse_time(str)
+      return nil unless str
+      Time.parse(str)
+    rescue ArgumentError
+      nil
+    end
+
+    # Get a human-readable label for a date
+    #
+    # @param time [Time] Time to generate label for
+    # @return [String] Date label (e.g., "Today", "Tomorrow", "Friday, January 24")
+    def date_label(time)
+      today = Date.today
+      date = time.to_date
+
+      if date == today
+        "Today"
+      elsif date == today + 1
+        "Tomorrow"
+      else
+        time.strftime("%A, %B %-d")
+      end
+    end
+  end
+
+  # Represents a single hourly forecast period
+  class HourlyPeriod
+    # @return [Integer] Period number
+    attr_reader :number
+
+    # @return [Time, nil] Start time of the period
+    attr_reader :start_time
+
+    # @return [Time, nil] End time of the period
+    attr_reader :end_time
+
+    # @return [Boolean] Whether this is a daytime period
+    attr_reader :is_daytime
+
+    # @return [Integer] Temperature value
+    attr_reader :temperature
+
+    # @return [String] Temperature unit (e.g., "F")
+    attr_reader :temperature_unit
+
+    # @return [String, nil] Temperature trend
+    attr_reader :temperature_trend
+
+    # @return [Integer, nil] Probability of precipitation (0-100)
+    attr_reader :probability_of_precipitation
+
+    # @return [String] Wind speed (e.g., "10 mph")
+    attr_reader :wind_speed
+
+    # @return [String] Wind direction (e.g., "NW")
+    attr_reader :wind_direction
+
+    # @return [String] Short forecast description
+    attr_reader :short_forecast
+
+    # @return [String] URL to forecast icon
+    attr_reader :icon
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # Initialize an HourlyPeriod from API response data
+    #
+    # @param data [Hash] Parsed JSON period data
+    def initialize(data)
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Check if this is a daytime period
+    #
+    # @return [Boolean] True if daytime period
+    def daytime?
+      @is_daytime
+    end
+
+    # Get a formatted string representation of the period
+    #
+    # @return [String] Formatted period string
+    def to_s
+      time_str = @start_time.strftime("%-l%P")
+      "#{time_str}: #{@temperature}°#{@temperature_unit} - #{@short_forecast}"
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON period data
+    # @return [void]
+    def parse_data(data)
+      @number = data["number"]
+      @start_time = parse_time(data["startTime"])
+      @end_time = parse_time(data["endTime"])
+      @is_daytime = data["isDaytime"]
+      @temperature = data["temperature"]
+      @temperature_unit = data["temperatureUnit"]
+      @temperature_trend = data["temperatureTrend"]
+      @probability_of_precipitation = data.dig("probabilityOfPrecipitation", "value")
+      @wind_speed = data["windSpeed"]
+      @wind_direction = data["windDirection"]
+      @short_forecast = data["shortForecast"]
+      @icon = data["icon"]
+    end
+
+    # Parse an ISO8601 time string
+    #
+    # @param str [String, nil] Time string
+    # @return [Time, nil] Parsed time or nil
+    def parse_time(str)
+      return nil unless str
+      Time.parse(str)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/nws/observation.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module NWS
+  # Represents a weather observation from a station
+  class Observation
+    # @return [Station, nil] The station this observation is from
+    attr_reader :station
+
+    # @return [Time, nil] Timestamp of the observation
+    attr_reader :timestamp
+
+    # @return [String, nil] Text description of conditions (e.g., "Partly Cloudy")
+    attr_reader :text_description
+
+    # @return [Hash] Raw API response data
+    attr_reader :raw_data
+
+    # @return [Float, nil] Temperature in Celsius
+    attr_reader :temperature_c
+
+    # @return [Float, nil] Dewpoint in Celsius
+    attr_reader :dewpoint_c
+
+    # @return [Float, nil] Relative humidity percentage
+    attr_reader :relative_humidity
+
+    # @return [Float, nil] Wind speed in km/h
+    attr_reader :wind_speed_kmh
+
+    # @return [Integer, nil] Wind direction in degrees
+    attr_reader :wind_direction
+
+    # @return [Float, nil] Wind gust speed in km/h
+    attr_reader :wind_gust_kmh
+
+    # @return [Float, nil] Barometric pressure in Pascals
+    attr_reader :barometric_pressure
+
+    # @return [Float, nil] Visibility in meters
+    attr_reader :visibility_m
+
+    # @return [Float, nil] Heat index in Celsius
+    attr_reader :heat_index_c
+
+    # @return [Float, nil] Wind chill in Celsius
+    attr_reader :wind_chill_c
+
+    # Initialize an Observation from API response data
+    #
+    # @param data [Hash] Parsed JSON response from the observations API
+    # @param station [Station, nil] The station this observation is from
+    def initialize(data, station: nil)
+      @station = station
+      @raw_data = data
+      parse_data(data)
+    end
+
+    # Get temperature in Fahrenheit
+    #
+    # @return [Float, nil] Temperature in Fahrenheit
+    def temperature_f
+      celsius_to_fahrenheit(@temperature_c)
+    end
+
+    # Get dewpoint in Fahrenheit
+    #
+    # @return [Float, nil] Dewpoint in Fahrenheit
+    def dewpoint_f
+      celsius_to_fahrenheit(@dewpoint_c)
+    end
+
+    # Get heat index in Fahrenheit
+    #
+    # @return [Float, nil] Heat index in Fahrenheit
+    def heat_index_f
+      celsius_to_fahrenheit(@heat_index_c)
+    end
+
+    # Get wind chill in Fahrenheit
+    #
+    # @return [Float, nil] Wind chill in Fahrenheit
+    def wind_chill_f
+      celsius_to_fahrenheit(@wind_chill_c)
+    end
+
+    # Get wind speed in mph
+    #
+    # @return [Float, nil] Wind speed in mph
+    def wind_speed_mph
+      kmh_to_mph(@wind_speed_kmh)
+    end
+
+    # Get wind gust speed in mph
+    #
+    # @return [Float, nil] Wind gust speed in mph
+    def wind_gust_mph
+      kmh_to_mph(@wind_gust_kmh)
+    end
+
+    # Get visibility in miles
+    #
+    # @return [Float, nil] Visibility in miles
+    def visibility_miles
+      return nil unless @visibility_m
+      (@visibility_m / 1609.34).round(2)
+    end
+
+    # Get barometric pressure in inches of mercury
+    #
+    # @return [Float, nil] Pressure in inHg
+    def barometric_pressure_inhg
+      return nil unless @barometric_pressure
+      (@barometric_pressure / 3386.39).round(2)
+    end
+
+    # Get a brief summary of current conditions
+    #
+    # @return [String] Summary string (e.g., "72°F, Partly Cloudy")
+    def summary
+      parts = []
+      parts << "#{temperature_f.round(0)}°F" if temperature_f
+      parts << text_description if text_description
+      parts.join(", ")
+    end
+
+    # Get a formatted string representation of the observation
+    #
+    # @return [String] Multi-line formatted string
+    def to_s
+      lines = []
+      lines << "Current Conditions (#{timestamp&.strftime('%Y-%m-%d %I:%M %p')})"
+      lines << "  Temperature: #{temperature_f&.round(1)}°F" if temperature_f
+      lines << "  Conditions: #{text_description}" if text_description
+      lines << "  Humidity: #{relative_humidity&.round(0)}%" if relative_humidity
+      lines << "  Dewpoint: #{dewpoint_f&.round(1)}°F" if dewpoint_f
+      lines << "  Wind: #{wind_direction}° at #{wind_speed_mph&.round(1)} mph" if wind_speed_mph
+      lines << "  Wind Gusts: #{wind_gust_mph&.round(1)} mph" if wind_gust_mph
+      lines << "  Visibility: #{visibility_miles} miles" if visibility_miles
+      lines << "  Pressure: #{barometric_pressure_inhg} inHg" if barometric_pressure_inhg
+      lines.join("\n")
+    end
+
+    private
+
+    # Parse API response data into instance variables
+    #
+    # @param data [Hash] Parsed JSON response
+    # @return [void]
+    def parse_data(data)
+      props = data["properties"] || {}
+
+      @timestamp = parse_time(props["timestamp"])
+      @text_description = props["textDescription"]
+      @temperature_c = extract_value(props["temperature"])
+      @dewpoint_c = extract_value(props["dewpoint"])
+      @relative_humidity = extract_value(props["relativeHumidity"])
+      @wind_speed_kmh = extract_value(props["windSpeed"])
+      @wind_direction = extract_value(props["windDirection"])
+      @wind_gust_kmh = extract_value(props["windGust"])
+      @barometric_pressure = extract_value(props["barometricPressure"])
+      @visibility_m = extract_value(props["visibility"])
+      @heat_index_c = extract_value(props["heatIndex"])
+      @wind_chill_c = extract_value(props["windChill"])
+    end
+
+    # Extract the value from a measurement object
+    #
+    # @param measurement [Hash, nil] Measurement object with "value" key
+    # @return [Float, nil] The extracted value
+    def extract_value(measurement)
+      return nil unless measurement.is_a?(Hash)
+      measurement["value"]
+    end
+
+    # Parse an ISO8601 time string
+    #
+    # @param str [String, nil] Time string
+    # @return [Time, nil] Parsed time or nil
+    def parse_time(str)
+      return nil unless str
+      Time.parse(str)
+    rescue ArgumentError
+      nil
+    end
+
+    # Convert Celsius to Fahrenheit
+    #
+    # @param c [Float, nil] Temperature in Celsius
+    # @return [Float, nil] Temperature in Fahrenheit
+    def celsius_to_fahrenheit(c)
+      return nil unless c
+      (c * 9.0 / 5.0) + 32
+    end
+
+    # Convert km/h to mph
+    #
+    # @param kmh [Float, nil] Speed in km/h
+    # @return [Float, nil] Speed in mph
+    def kmh_to_mph(kmh)
+      return nil unless kmh
+      kmh * 0.621371
+    end
+  end
+end