rubyweather 0.9.1

data/README

@@ -0,0 +1,113 @@
+= RubyWeather
+
+Author::    Matt Zukowski  (http://blog.roughest.net)
+Copyright:: Copyright (c) 2006 Urbacon Ltd.
+License::   GNU Lesser General Public License v2.1 (LGPL 2.1)
+
+<b>RubyWeather is a Ruby[http://ruby-lang.org] library for fetching weather-related data from weather.com[http://www.weather.com/services/xmloap.html].</b>
+
+Simple usage example:
+
+require 'rubygems'
+require_gem 'rubyweather'
+
+require 'weather'
+
+service = Weather::Service.new
+service.partner_id = <b>your partner id</b>
+service.license_key = <b>your license key</b>
+
+locations = service.find_location('Toronto')
+puts "Matching Locations: " + locations.inspect
+
+The above will print out a list of available locations and their codes. We can
+now use these codes to fetch the weather data for our city:
+
+forecast = service.fetch_forecast("CAXX0504", 5)
+
+puts "Location: %s" % forecast.location_name
+
+puts "Current Temperature: %s" % forecast.current.temperature
+puts "Current Windspeed: %s" % forecast.current.wind.speed
+
+puts "Tomorrow's High: %s" % forecast.tomorrow.high
+puts "Tomorrow's Outlook: %s" % forecast.tomorrow.outlook
+puts "Tomorrow's Wind Direction: %s" % forecast.tomorrow.wind.direction
+
+Forecasts for days in the future are accessed via <tt>forecast.day(#)</tt> where <tt>#</tt> is the number of day sinto the future
+(assuming that you've fetched data for as many days in your <tt>service.fetch_forecast</tt> request):
+
+puts "High 3 days from now: %s" % forecast.day(3).high
+puts "Probability of precipitation 4 days from now: %s" % forecast.day(4).pop
+
+There are a lot of attributes you can fetch for a forecast day. Here are just a few:
+
+<tt>temp</tt>, <tt>temperature</tt>, <tt>temp</tt>::
+The temperature. For future days this is equivalent to the low for nighttime and high for daytime.
+<tt>icon</tt>::
+The number of the icon gif file from the weather.com SDK[http://www.weather.com/services/xmloap.html] that
+identifies the conditions (e.g. a little icon of a cloud with rain, or sun, or whatever).
+<tt>outlook</tt>, <tt>outlook_brief</tt>::
+Brief text describing the conditions (e.g. "Mostly Cloudy", "Rain", "Scattered T-Storms"). An abbreviated
+version is available in <tt>outlook_brief</tt> (e.g. "M Cloudy", "Scat T-Storms").
+<tt>low</tt>, <tt>lo</tt>::
+The forecasted low temperature. (Not available for current conditions)
+<tt>high</tt>, <tt>hi</tt>::
+The forecasted high temperature. (Not available for current conditions)
+<tt>wind</tt>, <tt>wind.direction</tt>, <tt>wind.speed</tt>, <tt>wind.heading</tt>::
+Wind conditions. The <tt>wind</tt> attribute returns an object with sub-attributes.
+<tt>pop</tt>, <tt>ppcp</tt>::
+Probability of precipitation.
+<tt>date</tt>::
+The date that this forecast is for, returned as a ruby Time object.
+<tt>sunrise</tt>::
+The time of sunrise on the day of the forecast.
+<tt>sunset</tt>::
+The time of sunset on the day of the forecast.
+
+Additionally, all (or at least most) of the attributes for a given day in the raw weather.com xml data are
+also available. For example, you can call forecast.tomorrow.dewp to get the dewpoint, because the xml file
+contains a <tt>dewp</tt> element for that day. Have a look at #test/test_weather.xml to see what data is
+available in the xml file. Note though that raw xml elements will be returned as a string, without any nice
+class casting or unit conversion.
+
+I encourage other programmers to add more functionality to the lib/forecast.rb module to provide better
+accessor methods for the underlying xml data.
+
+== Download
+
+You can download the latest stable version of RubyWeather from http://rubyforge.org/projects/rubyweather/.
+Alternatively, the files <em>may</em> be available from http://roughest.net/rubyweather (but no promises -- the 
+rubyforge site is a better bet).
+
+You can also check out the latest copy via subversion from svn://rubyforge.org//var/svn/rubyweather/trunk. If you would
+like to contribute back your changes to the code, please contact me via the rubyforge project site to obtain a subversion
+account.
+
+== Note
+
+To use this library you will need a partner id and license key from
+weather.com. The service is completely free, but requires that you agree
+to weather.com's legal stuff, which, among other things, requires your software
+to include a link back to the weather.com website (although this is not actually
+enforced in any way by the service).
+
+To obtain the free license visit http://www.weather.com/services/xmloap.html.
+This will also allow you to download an SDK that includes nice weather icons for
+use with the data.
+
+== License
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation; either version 2 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program (see the file called LICENSE); if not, write to the
+Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301  USA

data/lib/forecast.rb

@@ -0,0 +1,318 @@
+#
+# Author::    Matt Zukowski  (http://blog.roughest.net)
+# Copyright:: Copyright (c) 2006 Urbacon Ltd.
+# License::   GNU Lesser General Public License v2.1 (LGPL 2.1)
+#
+
+require File.dirname(__FILE__) + '/util'
+
+module Weather
+
+  # Namespace module for weather data objects.
+  module Forecast
+  
+    # Contains several days of weather data.
+    # The forecast object includes the Enumerable mixin, so that you can iterate
+    # over all of the days in the forecast using the standard ruby mechanisms
+    # (i.e. <tt>myforecast.each { |d| print d.outlook }</tt>).
+    class Forecast      
+      include Enumerable
+      
+      attr_reader :xml
+      
+      # Instantiate a Forecast object from the specified Weather.com REXML::Document.
+      def initialize(weather_xmldoc)
+        if (not weather_xmldoc.kind_of? REXML::Document)
+          raise "The xml document given to the Forecast constructor must be a valid REXML::Document"
+        end
+        
+        @xml = weather_xmldoc
+      end
+      
+      # Returns the current conditions as a Conditions object.
+      def current
+        CurrentConditions.new(xml.root.elements['cc'])
+      end
+      
+      # Alias for day(1)
+      def tomorrow
+        day(1)
+      end
+      
+      # Returns the conditions for the given day (0 = today, 1 = tomorrow, etc.)
+      # The maximum day number depends on the data available in the xml that was used to create this Forecast.
+      def day(num)
+        element = xml.root.elements['dayf'].elements["day[@d='#{num.to_s}']"]
+        if not element
+          case num
+            when 0 then daydisplay = "today"
+            when 1 then daydisplay = "tomorrow"
+            else daydisplay = "#{num} days from now"
+          end
+          raise "Sorry, there is no data available for #{daydisplay}"
+        else
+          Day.new(element)
+        end
+      end
+      
+      # Returns the conditions for the given night (0 = tonight, 1 = tomorrow night, etc.)
+      # The maximum day number depends on the data available in the xml that was used to create this Forecast.
+      def night(num)
+        element = xml.root.elements['dayf'].elements["day[@d='#{num.to_s}']"]
+        Night.new(element)
+      end
+      
+      # Iterates over all of the days in this Forecast.
+      def each(&block)
+        first = true
+        REXML::XPath.match(xml, "//dayf/day").each do |dxml|
+          d = Day.new(dxml)
+          
+          # if it is after 3 PM, use current conditions
+          if Time.now > Time.local(d.date.year, d.date.month, d.date.day, 15)
+            d = current
+          end
+          
+          yield d
+          
+          first = false if first
+        end
+      end
+      
+      # Returns the full human-readable name of the place that this Forecast is for.
+      def location_name
+        xml.root.elements['loc'].elements['dnam'].text
+      end
+      
+      # Returns the name of the city that this Forecast is for.
+      def location_city
+        xml.root.elements['loc'].elements['dnam'].text.split(",").first
+      end
+      
+      # The location code of the weather station that this Forecast is for.
+      def location_code
+        xml.root.elements['loc'].attributes['id']
+      end
+      
+      # Returns true if the units returned by this Forecast will be in the metric system (i.e. Celcius).
+      def metric?              
+        xml.root.elements['head'].elements['ut'].text == "C"
+      end
+    end
+    
+    # Abstract class that all Forecast entities (roughly "days") are based on.
+    class Conditions
+    
+      # For elements in the forecast that we have not defined an explicit accessor,
+      # this allows accessing the raw underlying data in the forecast xml.
+      def method_missing(symbol)
+        begin
+          return @xml.elements[symbol.to_s].text
+        rescue NoMethodError
+          return "N/A"
+        end
+      end
+      
+      # Returns the wind conditions as an anonymous object (i.e. wind.d for wind
+      # direction, wind.s for wind speed, etc.) See the <wind> element in the 
+      # weather.com XML data spec for more info.
+      def wind
+        fix_wind(complex_attribute(@xml.elements['wind']))
+      end
+    
+      private
+      # Returns the element specified by name as a cleaned-up temperature value.
+      # That is, if the temperature is "N/A", then nil is returned; otherwise
+      # the value is converted to an integer.
+      def clean_temp(name)
+        temp = @xml.elements[name].text
+      
+        if (temp == "N/A")
+          return nil
+        else
+          return temp.to_i
+        end
+      end
+      
+      # Return the given xml element as an anonymous object, with the text nodes of the element's
+      # immediate children available as accessor methods.
+      # This allows for accessing attributes that have child elements (i.e. wind, bar, etc.)
+      # as anonymous objects (i.e. wind.d for wind direction, wind.s for wind speed, etc.)
+      def complex_attribute(objxml)
+        obj = {}
+        class << obj
+          def method_missing(name)
+            return self[name.to_s]
+          end
+        end
+        
+        objxml.elements.each do |element|
+          obj[element.name] = element.text
+        end
+        
+        return obj
+      end
+      
+      def fix_wind(obj)
+        obj['heading'] = obj.t
+        obj['direction'] = obj.d.to_i
+        obj['speed'] = obj.s.to_i
+        
+        return obj
+      end
+    end
+    
+    # Represents the current weather conditions.
+    class CurrentConditions < Conditions
+      attr_reader :xml
+      
+      @xml
+      
+      def initialize(element)
+        if (not element.kind_of? REXML::Element)
+          raise "The xml element given to the Day/Night constructor must be a valid REXML::Element"
+        end
+        @xml = element
+      end
+      
+      def icon
+        xml.elements['icon'].text.to_i
+      end
+      
+      def temp
+        clean_temp('tmp')
+      end
+      alias_method :tmp, :temp
+      alias_method :temperature, :temp
+      
+      def outlook
+        xml.elements['t'].text
+      end
+      
+      def outlook_brief
+        xml.elements['bt'].text
+      end
+      
+      def pop
+        nil
+      end
+      alias_method :ppcp, :pop
+      
+      def date
+        Time.now
+      end
+    end
+    
+    # Abstract class representing either a day or night in the daily forecast (note that "future" can include today).
+    class FutureConditions < Conditions
+      attr_reader :xml
+    
+      @xml
+    
+      def initialize(element)
+        if (not element.kind_of? REXML::Element)
+          raise "The xml element given to the Day/Night constructor must be a valid REXML::Element"
+        end
+        @xml = element
+      end
+      
+      def method_missing(name)
+        begin
+          return mypart.elements[name.to_s].text
+        rescue NoMethodError
+          return "N/A"
+        end
+      end
+      
+      def wind
+        fix_wind(complex_attribute(mypart.elements['wind']))
+      end
+      
+      def date
+        # FIXME: this will break if rolling over to next year (i.e. fetched 5 days into the future on Dec 30), since today's year is assumed
+        mon, day = @xml.attributes['dt'].split(" ")
+        Time.local(Time.now.year, mon, day)
+      end
+      
+      def icon
+        mypart.elements['icon'].text.to_i
+      end
+      
+      def high
+        clean_temp('hi')
+      end
+      alias_method :hi, :high
+      
+      def low
+        clean_temp('low')
+      end
+      alias_method :lo, :low
+      
+      
+      def outlook
+        mypart.elements['t'].text
+      end
+      
+      def outlook_brief
+        mypart.elements['bt'].text
+      end
+      
+      def pop
+        mypart.elements['ppcp'].text.to_i
+      end
+      alias_method :ppcp, :pop
+      
+      def sunrise
+        hour,minute = @xml.elements['sunr'].text.split(" ").first.split(":")
+        hour = hour.to_i
+        minute = minute.to_i
+        Time.local(date.year, date.month, date.day, hour, minute)
+      end
+      
+      def sunset
+        hour,minute = @xml.elements['suns'].text.split(" ").first.split(":")
+        hour = hour.to_i + 12 # add 12 since we need 24 hour clock and sunset is always (?) in the PM
+        minute = minute.to_i
+        Time.local(date.year, date.month, date.day, hour, minute)
+      end
+
+    end
+    
+    # The daytime part of the forecast for a given day.
+    class Day < FutureConditions
+      def initialize(element)
+        super(element)
+      end
+    
+      def temp
+        high
+      end
+      alias_method :tmp, :temp
+      alias_method :temperature, :temp
+    
+      private 
+        def mypart
+          @xml.elements['part[@p="d"]']
+        end
+    end
+    
+    # The nighttime part of a forecast for a given day.
+    class Night < FutureConditions
+      def initialize(element)
+        super(element)
+      end
+      
+      def temp
+        low
+      end
+      alias_method :tmp, :temp
+      alias_method :temperature, :temp
+    
+      private
+        def mypart
+          @xml.elements['part[@p="n"]']
+        end
+    end
+  end
+  
+end

data/lib/service.rb

@@ -0,0 +1,84 @@
+#
+# Author::    Matt Zukowski  (http://blog.roughest.net)
+# Copyright:: Copyright (c) 2006 Urbacon Ltd.
+# License::   GNU Lesser General Public License v2.1 (LGPL 2.1)
+#
+
+require 'net/http'
+require 'rexml/document'
+
+require File.dirname(__FILE__) + '/forecast'
+
+module Weather
+
+  # Interface for interacting with the weather.com service.
+  class Service
+    attr_writer :partner_id, :license_key, :imperial
+    attr_reader :partner_id, :license_key, :imperial
+    
+    # Returns the forecast data fetched from the weather.com xoap service for the given location and number of days.
+    def fetch_forecast(location_id, days = 5)
+      
+      # try to pull the partner_id and license_key from the environment if not already set
+      partner_id = ENV['WEATHER_COM_PARTNER_ID'] unless partner_id
+      license_key = ENV['WEATHER_COM_LICENSE_KEY'] unless license_key
+      
+      if imperial or (ENV.has_key? 'USE_IMPERIAL_UNITS' and ENV['USE_IMPERIAL_UNITS'])
+        imperial = true
+      else
+        imperial = false
+      end
+      
+      # NOTE: Strangely enough, weather.com doesn't seem to be enforcing the partner_id/license_key stuff. You can specify blank values for both
+      #       and the service will return the data just fine (actually, it will accept any value as valid). I'm commenting out these checks
+      #       for now, but we may need to re-enable these once weather.com figures out what's going on.
+      #if not partner_id
+      #  puts "WARNING: No partner ID has been set. Please obtain a partner ID from weather.com before attempting to fetch a forecast, otherwise the data you requested may not be available."
+      #end
+      #
+      #if not license_key
+      #  puts "WARNING: No license key has been set. Please obtain a license key from weather.com before attempting to fetch a forecast, otherwise the data you requested may not be available"
+      #end
+      
+      # default to metric (degrees fahrenheit are just silly :)
+      unit = imperial ? "s" : "m"
+      
+      host = "xoap.weather.com"
+      url = "/weather/local/#{location_id}?cc=*&dayf=#{days}&prod=xoap&par=#{partner_id}&key=#{license_key}&unit=#{unit}"
+      
+      # puts "Using url: "+url
+      
+      xml = Net::HTTP.get(host, url);
+      doc = REXML::Document.new(xml)
+
+      Forecast::Forecast.new(doc)
+    end
+    
+    # Returns the forecast data loaded from a file. This is useful for testing.
+    def load_forecast(filename)
+      file = File.new(filename)
+      doc = REXML::Document.new(file)
+      
+      Forecast::Forecast.new(doc)
+    end
+    
+    # Returns a hash containing location_code => location_name key-value pairs for the given location search string.
+    # In other words, you can use this to find a location code based on a city name, ZIP code, etc.
+    def find_location(search_string)
+      host = "xoap.weather.com"
+      # FIXME: need to do url encoding of the search string!
+      url = "/weather/search/search?where=#{search_string}"
+      
+      xml = Net::HTTP.get(host, url);
+      doc = REXML::Document.new(xml)
+      
+      locations = {}
+      
+      REXML::XPath.match(doc.root, "//loc").each do |loc|
+        locations[loc.attributes['id']] = loc.text
+      end
+      
+      return locations
+    end
+  end
+end