noaa 0.2.4

data/lib/noaa.rb

@@ -0,0 +1,63 @@
+begin
+  require 'time'
+  require 'nokogiri'
+  require 'geokit'
+rescue LoadError => e
+  if require 'rubygems' then retry
+  else raise(e)
+  end
+end
+
+%w(current_conditions forecast forecast_day http_service station station_writer).each { |file| require File.join(File.dirname(__FILE__), 'noaa', file) }
+
+# 
+# The NOAA singleton provides methods to conveniently access information from the NOAA weather feed.
+# For the most part, NOAA.current_conditions and NOAA.forecast will be the only entry point into the
+# NOAA API you will need; one exception is discussed below.
+#
+module NOAA
+  autoload :VERSION, File.join(File.dirname(__FILE__), 'noaa', 'version')
+
+  class <<self
+    # 
+    # Retrieve the current weather conditions for a given latitude and longitude. Returns an
+    # instance of NOAA::CurrentConditions.
+    #
+    #   NOAA.current_conditions(37.989, -77.507)  #=> NOAA::CurrentConditions encapsulating current conditions at this point
+    #
+    # <b>Note:</b> This method parses the stored list of all weather stations in the US and then finds the closest one to
+    # the given coordinates, as the NOAA XML API only takes a weather station ID as input. Clearly, this is an expensive
+    # operation; if your application needs to repeatedly request conditions for the same point, you will be much better off
+    # determining the current station once using NOAA::Station.closest_to, storing the station ID, and then passing it into
+    # NOAA.current_conditions_at_station when you need to get the latest conditions.
+    #
+    def current_conditions(lat, lng)
+      current_conditions_at_station(Station.closest_to(lat, lng).id)
+    end
+    
+    # 
+    # Retrieve the current weather conditions for a given weather station ID. Returns an
+    # instance of NOAA::CurrentConditions.
+    #
+    #   NOAA.current_conditions_at_station('KNYC')  #=> NOAA::CurrentConditions encapsulating current conditions in Central Park
+    #
+    # See discussion above regarding why this method is often preferable to simply calling #current_conditions.
+    #
+    def current_conditions_at_station(station_id)
+      CurrentConditions.from_xml(HttpService.new.get_current_conditions(station_id))
+    end
+
+    # 
+    # Retrieve daily forecast information for a given latitude and longitude. Returns
+    # an instance of NOAA::Forecast.
+    #
+    #   NOAA.forecast(4, 37.989, -77.507)  #=> NOAA::Forecast containing next four days of forecast data for given coordinates
+    #
+    # <b>Note:</b> The NOAA updates this data no more than once an hour, and asks that users of the API not request the forecast
+    # for a given location more frequently than that. For more information, please see http://www.nws.noaa.gov/xml/#frequency
+    #
+    def forecast(num_days, lat, lng)
+      Forecast.from_xml(HttpService.new.get_forecast(num_days, lat, lng))
+    end
+  end
+end

data/lib/noaa/current_conditions.rb

@@ -0,0 +1,185 @@
+module NOAA
+  # 
+  # Representation of the current conditions for a given observation point.
+  #
+  class CurrentConditions
+
+    class <<self
+      private :new
+
+      def from_xml(doc) #:nodoc:
+        new(doc)
+      end
+    end
+
+    def initialize(doc) #:notnew:
+      @doc = doc
+    end
+
+    #
+    # Time object containing the time at which these conditions were observed at the NOAA station
+    #
+    def observed_at
+      @observed_at ||= Time.parse(text_from_node('observation_time_rfc822'))
+    end
+
+    #
+    # Text description of the current weather conditions, e.g. "Fair"
+    #
+    def weather_description
+      @weather_description ||= text_from_node('weather')
+    end
+    alias_method :weather_summary, :weather_description
+
+    # 
+    # NWS code representing weather type. This distills the #weather_description
+    # into one of a much more manageable set of possibilities. Possible values are:
+    #
+    # - <code>:skc</code> - Clear
+    # - <code>:wind</code> - Windy
+    # - <code>:few</code> - A Few Clouds
+    # - <code>:sct</code> - Partly Cloudy
+    # - <code>:bkn</code> - Mostly Cloudy
+    # - <code>:ovc</code> - Overcast
+    # - <code>:ra1</code> - Light Rain
+    # - <code>:ra</code> - Rain
+    # - <code>:shra</code> - Rain Showers
+    # - <code>:tsra</code> - Thunderstorms
+    # - <code>:ip</code> - Hail
+    # - <code>:fzra</code> - Freezing Rain
+    # - <code>:mix</code> - Wintry Mix
+    # - <code>:sn</code> - Snow
+    # - <code>:fg</code> - Fog
+    # - <code>:smoke</code> - Smoke
+    # - <code>:dust</code> - Dust/Sand
+    # - <code>:mist</code> - Haze
+    # - <code>:svrtsra</code> - Tornado
+    # - <code>:fzrara</code> - Freezing Rain/Rain
+    # - <code>:raip</code> - Rain/Hail
+    # - <code>:rasn</code> - Rain/Snow
+    # - <code>:hi_shwrs</code> - Showers in Vicinity
+    # - <code>:hi_tsra</code> - Thunderstorm in Vicinity
+    #
+    # See http://www.weather.gov/xml/current_obs/weather.php for the NWS's list of possible
+    # descriptions and their type codes.
+    #
+    def weather_type_code
+      @weather_type_code ||= text_from_node('icon_url_name').gsub(/^n|\.jpg$/, '').to_sym
+    end
+
+    # 
+    # Return the NWS image URL for the current weather as string
+    #
+    def image_url
+      @image_url ||= "#{text_from_node('icon_url_base')}#{text_from_node('icon_url_name')}"
+    end
+
+    #
+    # The current temperature in the requested units.
+    #
+    #   conditions.temperature           #=> temperature in fahrenheit
+    #   conditions.temperature(:c)       #=> temperature in celsius
+    #   conditions.temperature(:kelvin)  #=> anything else raises an exception
+    #
+    def temperature(unit = :f)
+      text_from_node_with_unit('temp', unit, :f, :c).to_i
+    end
+
+    # 
+    # The current relative humidity percentage (0-100)
+    #
+    def relative_humidity
+      text_from_node('relative_humidity').to_i
+    end
+
+    # 
+    # The current cardinal or ordinal direction that the wind is coming from (e.g., "Northwest")
+    #
+    def wind_direction
+      text_from_node('wind_dir')
+    end
+
+    # 
+    # The current direction that the wind is coming from degrees (e.g. 330)
+    #
+    def wind_degrees
+      text_from_node('wind_degrees').to_i
+    end
+
+    # 
+    # The current wind speed in miles per hour as a float (e.g., 3.45)
+    #
+    def wind_speed
+      text_from_node('wind_mph').to_f
+    end
+
+    # 
+    # The current wind gust in miles per hour as a float, or nil if none
+    #
+    def wind_gust
+      text_from_node('wind_gust_mph').to_f
+    end
+
+    # 
+    # The current barometric pressure
+    #
+    #   conditions.pressure       #=> pressure in inches
+    #   conditions.pressure(:mb)  #=> pressure in millibars
+    #   conditions.pressure(:psi) #=> anything else raises an exception
+    #
+    def pressure(unit = :in)
+      text_from_node_with_unit('pressure', unit, :in, :mb).to_f
+    end
+
+    # 
+    # The current dew point.
+    #
+    #   conditions.dew_point           #=> dew point in fahrenheit
+    #   conditions.dew_point(:c)       #=> dew point in celsius
+    #   conditions.dew_point(:kelvin)  #=> anything else raises an exception
+    #
+    def dew_point(unit = :f)
+      text_from_node_with_unit('dewpoint', unit, :f, :c).to_i
+    end
+
+    # 
+    # The current heat index
+    #
+    #   conditions.heat_index           #=> heat index in fahrenheit
+    #   conditions.heat_index(:c)       #=> heat index in celsius
+    #   conditions.heat_index(:kelvin)  #=> anything else raises an exception
+    #
+    def heat_index(unit = :f)
+      text_from_node_with_unit('heat_index', unit, :f, :c).to_i
+    end
+
+    # 
+    # The current wind chill
+    #
+    #   conditions.wind_chill           #=> wind chill in fahrenheit
+    #   conditions.wind_chill(:c)       #=> wind chill in celsius
+    #   conditions.wind_chill(:kelvin)  #=> anything else raises an exception
+    #
+    def wind_chill(unit = :f)
+      text_from_node_with_unit('windchill', unit, :f, :c).to_i
+    end
+
+    # 
+    # The current visibility in miles
+    #
+    def visibility
+      text_from_node('visibility_mi').to_f
+    end
+
+    private
+
+    def text_from_node(element_name)
+      @doc.xpath("/current_observation/#{element_name}[1]/child::text()").first.to_s
+    end
+
+    def text_from_node_with_unit(element_name, unit, *allowed_units)
+      raise ArgumentError, "Unknown unit #{unit.inspect} - allowed units are #{allowed_units.inspect}" unless allowed_units.include?(unit)
+      text_from_node("#{element_name}_#{unit}")
+    end
+  end
+end

data/lib/noaa/forecast.rb

@@ -0,0 +1,108 @@
+module NOAA
+  # 
+  # A Forecast object represents a multi-day forecast for a particular place. The forecast for a given day can
+  # be accessed using the [] method; e.g. (assuming +forecast+ is a forecast for 12/20/2008 - 12/24/2008):
+  #
+  #   forecast[1]     #=> ForecastDay for 12/21/2008
+  #   forecast.length #=> 4
+  #   
+  class Forecast
+
+    class <<self
+      private :new
+
+      def from_xml(doc) #:nodoc:
+        new(doc)
+      end
+    end
+
+    def initialize(doc) #:noinit:
+      @doc = doc
+    end
+
+    # 
+    # The number of days provided by the forecast
+    #
+    def length
+      @length ||= @doc.find(%q{/dwml/data/time-layout[@summarization='24hourly'][1]/start-valid-time}).length
+    end
+
+    # 
+    # Get the ForecastDay for day i
+    #
+    #   forecast[1] #=> returns the ForecastDay for the second day
+    # 
+    def [](i)
+      forecast_days[i]
+    end
+
+    private
+
+    def forecast_days
+      @forecast_days ||= begin
+        days = []
+        length.times do |i|
+          days << day = NOAA::ForecastDay.new
+          day.starts_at = starts[i]
+          day.ends_at = ends[i]
+          day.high = maxima[i]
+          day.low = minima[i]
+          day.weather_summary = weather_summaries[i]
+          day.weather_type_code = weather_type_codes[i]
+          day.image_url = image_urls[i]
+          day.daytime_precipitation_probability = precipitation_probabilities[i*2]
+          day.evening_precipitation_probability = precipitation_probabilities[i*2+1]
+        end
+        days
+      end
+    end
+
+    def starts
+      @starts ||= @doc.find(%q{/dwml/data/time-layout[@summarization='24hourly'][1]/start-valid-time/text()}).map do |node|
+        Time.parse(node.to_s)
+      end
+    end
+
+    def ends
+      @ends ||= @doc.find(%q{/dwml/data/time-layout[@summarization='24hourly'][1]/end-valid-time/text()}).map do |node|
+        Time.parse(node.to_s)
+      end
+    end
+
+    def maxima
+      @maxima ||= @doc.find(%q{/dwml/data/parameters[1]/temperature[@type='maximum'][@units='Fahrenheit'][1]/value/text()}).map do |node|
+        node.to_s.to_i
+      end
+    end
+
+    def minima
+      @minima ||= @doc.find(%q{/dwml/data/parameters[1]/temperature[@type='minimum'][@units='Fahrenheit'][1]/value/text()}).map do |node|
+        node.to_s.to_i
+      end
+    end
+
+    def weather_summaries
+      @weather_summaries ||= @doc.find(%q{/dwml/data/parameters[1]/weather[1]/weather-conditions}).map do |node|
+        node['weather-summary'].to_s
+      end
+    end
+
+    def image_urls
+      @image_urls ||= @doc.find(%q{/dwml/data/parameters[1]/conditions-icon/icon-link/text()}).map do |node|
+        node.to_s
+      end
+    end
+
+    def weather_type_codes
+      @weather_type_codes ||= image_urls.map do |url|
+        url.match(/n?([a-z_]+)\d*\.jpg$/)[1].to_sym
+      end
+    end
+
+    def precipitation_probabilities
+      @precipitation_probabilities ||= @doc.find(%q{/dwml/data/parameters[1]/probability-of-precipitation[1]/value/text()}).map do |node|
+        node.to_s.to_i
+      end
+    end
+  end
+end

data/lib/noaa/forecast_day.rb

@@ -0,0 +1,38 @@
+module NOAA
+  # 
+  # A ForecastDay contains forecast data for a single day. Each day should start at 6am and
+  # end at 6am the following day (assuming that is invariant on the part of the NOAA's data
+  # feed). ForecastDay objects are accessed using NOAA::Forecast#[]
+  class ForecastDay
+    # Time when this forecast's valid time span begins
+    attr_reader :starts_at
+
+    # Time when this forecast's valid time span ends
+    attr_reader :ends_at
+
+    # High temperature for the day in Fahrenheit
+    attr_reader :high
+
+    # Low temperature for the day in Fahrenheit
+    attr_reader :low
+
+    # String summary of weather (e.g., 'Fair')
+    attr_reader :weather_summary
+    alias_method :weather_description, :weather_summary
+
+    # Symbol representing NOAA weather type. See NOAA::CurrentConditions#weather_type_code
+    attr_reader :weather_type_code
+
+    # URL string for NOAA weather image
+    attr_reader :image_url
+
+    # Percentage probability of precipitation during the day, between 6am and 6pm, as an integer (0-100)
+    attr_reader :daytime_precipitation_probability
+
+    # Percentage probability of precipitation during the evening/night, between 6pm and 6am, as an integer (0-100)
+    attr_reader :evening_precipitation_probability
+
+    attr_writer :starts_at, :ends_at, :high, :low, :weather_summary, :weather_type_code, :image_url, #:nodoc:
+                :daytime_precipitation_probability, :evening_precipitation_probability #:nodoc:
+  end
+end

data/lib/noaa/http_service.rb

@@ -0,0 +1,19 @@
+module NOAA
+  class HttpService #:nodoc:
+    def initialize(http = Net::HTTP)
+      @HTTP = http
+    end
+
+    def get_current_conditions(station_id)
+      LibXML::XML::Document.string(@HTTP.get(URI.parse("http://www.weather.gov/xml/current_obs/#{station_id}.xml")))
+    end
+
+    def get_forecast(num_days, lat, lng)
+      LibXML::XML::Document.string(@HTTP.get(URI.parse("http://www.weather.gov/forecasts/xml/sample_products/browser_interface/ndfdBrowserClientByDay.php?lat=#{lat}&lon=#{lng}&format=24+hourly&numDays=#{num_days}")))
+    end
+
+    def get_station_list
+      LibXML::XML::Document.string(@HTTP.get(URI.parse("http://www.weather.gov/xml/current_obs/index.xml")))
+    end
+  end
+end

data/lib/noaa/station.rb

@@ -0,0 +1,111 @@
+module NOAA
+  # 
+  # Data about an NOAA observation station. When accessing current conditions, the NOAA XML API
+  # takes a station ID as input; thus, to find the current conditions for an arbitrary location, one
+  # must first determine the closest weather station to that location. The NOAA.current_conditions
+  # method performs this task implicitly; however, for applications that need to find conditions
+  # for the same location(s) repeatedly, it is far more efficient to find the closest weather station
+  # once, store that information, and then query directly against the weather station when updated
+  # conditions are needed.
+  #
+  # Station data is stored in a YAML file that is created using the <tt>noaa-update-stations</tt> executable.
+  # Be sure to run this command at least once when you first install the NOAA library, and any time
+  # thereafter that you would like to get the latest list of stations. I don't imagine the list
+  # changes very often but I don't really have any idea.
+  #
+  class Station
+    class <<self
+      attr_writer :stations_file #:nodoc:
+
+      #
+      # Retrieve information about a station given a station ID
+      #
+      #   NOAA::Station.find('KNYC')  #=> NOAA::Station object for the Central Park station
+      def find(id)
+        stations.find { |station| station.id == id }
+      end
+
+      # 
+      # Find the station closest to a given location. Can accept arguments in any of the following
+      # three forms (all are equivalent):
+      #
+      #   NOAA::Station.closest_to(37.989, -77.507)
+      #   NOAA::Station.closest_to([37.989, -77.507])
+      #   NOAA::Station.closest_to(GeoKit::LatLng.new(37.989, -77.507))
+      def closest_to(*args)
+        if args.length == 1
+          if args.first.respond_to?(:distance_to)
+            closest_to_coordinates(args.first)
+          elsif %w(first last).all? { |m| args.first.respond_to?(m) }
+            closest_to_lat_lng(args.first)
+          else
+            raise ArgumentError, "expected two-element Array or GeoKit::LatLng"
+          end
+        elsif args.length == 2
+          closest_to_lat_lng(args)
+        else
+          raise ArgumentError, "closest_to() will accept one Array argument, one GeoKit::LatLng argument, or two FixNum arguments"
+        end
+      end
+
+      private
+
+      def closest_to_lat_lng(pair)
+        closest_to_coordinates(GeoKit::LatLng.new(pair.first, pair.last))
+      end
+
+      def closest_to_coordinates(coordinates)
+        stations.map do |station|
+          [coordinates.distance_to(station.coordinates), station]
+        end.min do |p1, p2|
+          p1.first <=> p2.first # compare distance
+        end[1]
+      end
+
+      def stations
+        File.open(stations_file) do |file|
+          yaml = YAML.load(file) || raise("Can't parse #{file.path} - be sure to run noaa-update-stations")
+          yaml.map { |station_hash| new(station_hash) }
+        end
+      end
+
+      def stations_file
+        @stations_file ||= File.join(File.dirname(__FILE__), '..', '..', 'data', 'stations.yml')
+      end
+    end
+
+    # GeoKit::LatLng containing the station's coordinates
+    attr_reader :coordinates
+
+    # Station ID (e.g., "KNYC")
+    attr_reader :id
+
+    # Station name (e.g., "New York City, Central Park")
+    attr_reader :name
+    
+    # Two-digit abbreviation for state in which station resides (e.g., "NY")
+    attr_reader :state
+    
+    attr_reader :xml_url #:nodoc:
+
+    def initialize(properties)
+      @id, @name, @state, @xml_url = %w(id name state xml_url).map do |p|
+        properties[p]
+      end
+      @coordinates = GeoKit::LatLng.new(properties['latitude'], properties['longitude'])
+    end
+    
+    # Latitude of station
+    def latitude
+      @coordinates.lat
+    end
+    alias_method :lat, :latitude
+
+    # Longitude of station
+    def longitude
+      @coordinates.lng
+    end
+    alias_method :lng, :longitude
+    alias_method :lon, :longitude
+  end
+end