yahoo-weather 1.1.0 → 1.2.0

data/lib/yahoo-weather/astronomy.rb

@@ -0,0 +1,13 @@
+# Describes astronomy information for a particular location.
+class YahooWeather::Astronomy
+  # a Time object detailing the sunrise time for a location.
+  attr_reader :sunrise
+
+  # a Time object detailing the sunset time for a location.
+  attr_reader :sunset
+
+  def initialize (payload)
+    @sunrise = YahooWeather._parse_time(payload['sunrise'])
+    @sunset = YahooWeather._parse_time(payload['sunset'])
+  end
+end

data/lib/yahoo-weather/atmosphere.rb

@@ -0,0 +1,40 @@
+# Describes the specific atmospheric conditions at a location.
+class YahooWeather::Atmosphere
+  # Constants representing the state of the barometric pressure.
+  #
+  class Barometer
+    STEADY = 'steady'
+    RISING = 'rising'
+    FALLING = 'falling'
+
+    # lists all possible barometer constants
+    ALL = [ STEADY, RISING, FALLING ]
+  end
+
+  # the humidity of the surroundings.
+  attr_reader :humidity
+
+  # the visibility level of the surroundings
+  attr_reader :visibility
+
+  # the pressure level of the surroundings.
+  attr_reader :pressure
+
+  # the state of the barometer, defined as one of the
+  # YahooWeather::Atmosphere::Barometer constants.
+  attr_reader :barometer
+
+  def initialize (payload)
+    @humidity = payload['humidity'].to_i
+    @visibility = payload['visibility'].to_i
+    @pressure = payload['pressure'].to_f
+
+    # map barometric pressure direction to appropriate constant
+    @barometer = nil
+    case payload['rising'].to_i
+    when 0: @barometer = Barometer::STEADY
+    when 1: @barometer = Barometer::RISING
+    when 2: @barometer = Barometer::FALLING
+    end
+  end
+end

data/lib/yahoo-weather/client.rb

@@ -0,0 +1,70 @@
+# The main client object through which the Yahoo! Weather service may be accessed.
+class YahooWeather::Client
+  # the url with which we obtain weather information from yahoo
+  @@API_URL = "http://weather.yahooapis.com/forecastrss"
+
+  def initialize (api_url = @@API_URL)
+    @api_url = api_url
+  end
+
+  # Returns a YahooWeather::Response object detailing the current weather
+  # information for the specified location.
+  #
+  # The lookup requires the unique WOEID for the location whose
+  # weather is sought.. To find your WOEID, browse or search for your
+  # city from the Weather (http://weather.yahoo.com/) home page. The
+  # WOEID is in the URL for the forecast page for that city. You can
+  # also get the WOEID by entering your zip code on the home page. For
+  # example, if you search for Los Angeles on the Weather home page,
+  # the forecast page for that city is
+  # http://weather.yahoo.com/united-states/california/los-angeles-2442047/. The
+  # WOEID is 2442047.
+  #
+  # +units+ allows specifying whether to retrieve information in
+  # +Fahrenheit+ as YahooWeather::Units::FAHRENHEIT, or +Celsius+ as
+  # YahooWeather::Units::CELSIUS, and defaults to fahrenheit.
+  #
+  def lookup_by_woeid (woeid, units = 'f')
+    url = @api_url + '?w=' + CGI.escape(woeid.to_s) + '&u=' + CGI.escape(units)
+    _lookup(woeid, url)
+  end
+
+  # Returns a YahooWeather::Response object detailing the current weather
+  # information for the specified location.
+  #
+  # NOTE: This method is deprecated as Yahoo has deprecated this
+  # non-WOEID-based lookup function.  Please use the new
+  # +lookup_by_woeid+ method instead.
+  #
+  # +location+ can be either a US zip code or a location code.  Location
+  # codes can be looked up at http://weather.yahoo.com, where it will appear
+  # in the URL that results from searching on the city or zip code.  For
+  # instance, searching on 'Seattle, WA' results in a URL ending in
+  # 'USWA0395.html', so the location code for Seattle is 'USWA0395'.
+  #
+  # +units+ allows specifying whether to retrieve information in
+  # +Fahrenheit+ as YahooWeather::Units::FAHRENHEIT, or +Celsius+ as
+  # YahooWeather::Units::CELSIUS, and defaults to fahrenheit.
+  #
+  def lookup_location (location, units = 'f')
+    url = @api_url + '?p=' + CGI.escape(location) + '&u=' + CGI.escape(units)
+    _lookup(location, url)
+  end
+
+  private
+
+    def _lookup (src, url)
+      begin
+        response = Net::HTTP.get_response(URI.parse(url)).body.to_s
+
+      rescue => e
+        raise RuntimeError.new("failed to get weather [src=#{src}, " +
+                               "url=#{url}, e=#{e}].")
+      end
+
+      # create the response object
+      doc = Nokogiri::XML.parse(response)
+      YahooWeather::Response.new(src, url, doc)
+    end
+
+end

data/lib/yahoo-weather/condition.rb

@@ -0,0 +1,20 @@
+class YahooWeather::Condition
+  # the Yahoo! Weather condition code, as detailed at http://developer.yahoo.com/weather.
+  attr_reader :code
+
+  # the date and time associated with these conditions.
+  attr_reader :date
+
+  # the temperature of the location.
+  attr_reader :temp
+
+  # the brief prose text description of the weather conditions of the location.
+  attr_reader :text
+
+  def initialize (payload)
+    @code = payload['code'].to_i
+    @date = YahooWeather._parse_time(payload['date'])
+    @temp = payload['temp'].to_i
+    @text = payload['text']
+  end
+end

data/lib/yahoo-weather/forecast.rb

@@ -0,0 +1,29 @@
+# The forecasted weather conditions for a specific location.
+class YahooWeather::Forecast
+  # the brief name of the day associated with the forecast.
+  attr_reader :day
+
+  # the date associated with the forecast.
+  attr_reader :date
+
+  # the low temperature forecasted.
+  attr_reader :low
+
+  # the high temperature forecasted.
+  attr_reader :high
+
+  # the brief prose text description of the forecasted weather conditions.
+  attr_reader :text
+
+  # the Yahoo! Weather code associated with the forecast, per http://developer.yahoo.com/weather.
+  attr_reader :code
+
+  def initialize (payload)
+    @day = payload['day']
+    @date = YahooWeather._parse_time(payload['date'])
+    @low = payload['low'].to_i
+    @high = payload['high'].to_i
+    @text = payload['text']
+    @code = payload['code'].to_i
+  end
+end

data/lib/yahoo-weather/image.rb

@@ -0,0 +1,25 @@
+class YahooWeather::Image
+  # the height of the image in pixels.
+  attr_reader :height
+
+  # the url intended to be used as a link wrapping the image, for
+  # instance, to send the user to the main Yahoo Weather home page.
+  attr_reader :link
+
+  # the title of hte image.
+  attr_reader :title
+
+  # the full url to the image.
+  attr_reader :url
+
+  # the width of the image in pixels.
+  attr_reader :width
+
+  def initialize (payload)
+    @title = payload.xpath('title').first.content
+    @link = payload.xpath('link').first.content
+    @url = payload.xpath('url').first.content
+    @height = payload.xpath('height').first.content.to_i
+    @width = payload.xpath('width').first.content.to_i
+  end
+end

data/lib/yahoo-weather/location.rb

@@ -0,0 +1,17 @@
+# Describes a geographical location.
+class YahooWeather::Location
+  # the name of the city.
+  attr_reader :city
+
+  # the name of the country.
+  attr_reader :country
+
+  # the name of the region, such as a state.
+  attr_reader :region
+
+  def initialize (payload)
+    @city = payload['city']
+    @country = payload['country']
+    @region = payload['region']
+  end
+end

data/lib/yahoo-weather/response.rb

@@ -0,0 +1,85 @@
+# Describes the weather conditions for a particular requested location.
+class YahooWeather::Response
+  # a YahooWeather::Astronomy object detailing the sunrise and sunset
+  # information for the requested location.
+  attr_reader :astronomy
+
+  # a YahooWeather::Location object detailing the precise geographical names
+  # to which the requested location was mapped.
+  attr_reader :location
+
+  # a YahooWeather::Units object detailing the units corresponding to the
+  # information detailed in the response.
+  attr_reader :units
+
+  # a YahooWeather::Wind object detailing the wind information at the
+  # requested location.
+  attr_reader :wind
+
+  # a YahooWeather::Atmosphere object detailing the atmosphere information
+  # of the requested location.
+  attr_reader :atmosphere
+
+  # a YahooWeather::Condition object detailing the current conditions of the
+  # requested location.
+  attr_reader :condition
+
+  # a list of YahooWeather::Forecast objects detailing the high-level
+  # forecasted weather conditions for upcoming days.
+  attr_reader :forecasts
+
+  # the raw HTML generated by the Yahoo! Weather service summarizing current
+  # weather conditions for the requested location.
+  attr_reader :description
+
+  # a YahooWeather::Image record describing an image icon
+  # representing the current weather.
+  attr_reader :image
+
+  # the latitude of the location for which weather is detailed.
+  attr_reader :latitude
+
+  # the longitude of the location for which weather is detailed.
+  attr_reader :longitude
+
+  # a link to the Yahoo! Weather page with full detailed information on the
+  # requested location's current weather conditions.
+  attr_reader :page_url
+
+  # the location string initially requested of the service.
+  attr_reader :request_location
+
+  # the url with which the Yahoo! Weather service was accessed to build the response.
+  attr_reader :request_url
+
+  # the prose descriptive title of the weather information.
+  attr_reader :title
+
+  def initialize (request_location, request_url, doc)
+    # save off the request params
+    @request_location = request_location
+    @request_url = request_url
+
+    # parse the nokogiri xml document to gather response data
+    root = doc.xpath('/rss/channel').first
+
+    @astronomy = YahooWeather::Astronomy.new(root.xpath('yweather:astronomy').first)
+    @location = YahooWeather::Location.new(root.xpath('yweather:location').first)
+    @units = YahooWeather::Units.new(root.xpath('yweather:units').first)
+    @wind = YahooWeather::Wind.new(root.xpath('yweather:wind').first)
+    @atmosphere = YahooWeather::Atmosphere.new(root.xpath('yweather:atmosphere').first)
+    @image = YahooWeather::Image.new(root.xpath('image').first)
+
+    item = root.xpath('item').first
+    @condition = YahooWeather::Condition.
+      new(item.xpath('yweather:condition').first)
+    @forecasts = []
+    item.xpath('yweather:forecast').each { |forecast| 
+      @forecasts << YahooWeather::Forecast.new(forecast) }
+    @latitude = item.xpath('geo:lat').first.content.to_f
+    @longitude = item.xpath('geo:long').first.content.to_f
+    @page_url = item.xpath('link').first.content
+    @title = item.xpath('title').first.content
+    @description = item.xpath('description').first.content
+  end
+end

data/lib/yahoo-weather/units.rb

@@ -0,0 +1,24 @@
+# Describes the units of measure with which weather information is provided.
+class YahooWeather::Units
+  FAHRENHEIT = 'f'
+  CELSIUS = 'c'
+
+  # the units in which temperature is measured, e.g. +F+ for +Fahrenheit+ or +C+ for +Celsius+.
+  attr_reader :temperature
+
+  # the units in which distance is measured, e.g. +mi+ for +miles+.
+  attr_reader :distance
+
+  # the units in which pressure is measured, e.g. +in+ for +inches+.
+  attr_reader :pressure
+
+  # the units in which speed is measured, e.g. +mph+ for <tt>miles per hour</tt>.
+  attr_reader :speed
+
+  def initialize (payload)
+    @temperature = payload['temperature']
+    @distance = payload['distance']
+    @pressure = payload['pressure']
+    @speed = payload['speed']
+  end
+end

data/lib/yahoo-weather/wind.rb

@@ -0,0 +1,17 @@
+# Describes the specific wind conditions at a location.
+class YahooWeather::Wind
+  # the temperature factoring in wind chill.
+  attr_reader :chill
+
+  # the direction of the wind in degrees.
+  attr_reader :direction
+
+  # the speed of the wind.
+  attr_reader :speed
+
+  def initialize (payload)
+    @chill = payload['chill'].to_i
+    @direction = payload['direction'].to_i
+    @speed = payload['speed'].to_i
+  end
+end

data/test/test_api.rb

@@ -11,7 +11,9 @@ class TestAPI < Test::Unit::TestCase
     # check a seattle, wa zipcode
     request_location = '98103'
     response = @client.lookup_location(request_location)
-    _assert_valid_response(response, request_location, 'f', 'Seattle', 'WA', 'US')
+    _assert_valid_response(response, request_location, 
+                           YahooWeather::Units::FAHRENHEIT,
+                           'Seattle', 'WA', 'US')
   end
 
   def test_lookup_location
@@ -19,7 +21,9 @@ class TestAPI < Test::Unit::TestCase
     # yahoo weather developer page
     request_location = 'FRXX0076'
     response = @client.lookup_location(request_location)
-    _assert_valid_response(response, request_location, 'f', 'Paris', '', 'FR')
+    _assert_valid_response(response, request_location, 
+                           YahooWeather::Units::FAHRENHEIT, 
+                           'Paris', '', 'FR')
   end
 
   def test_units
@@ -29,100 +33,118 @@ class TestAPI < Test::Unit::TestCase
     country = 'US'
 
     # check explicitly specifying fahrenheit units
-    response = @client.lookup_location(request_location, 'f')
-    _assert_valid_response(response, request_location, 'f', city, region, country)
+    response = @client.lookup_location(request_location, 
+                                       YahooWeather::Units::FAHRENHEIT)
+    _assert_valid_response(response, request_location, 
+                           YahooWeather::Units::FAHRENHEIT, 
+                           city, region, country)
 
     # check alternate units
-    response = @client.lookup_location(request_location, 'c')
-    _assert_valid_response(response, request_location, 'c', city, region, country)
+    response = @client.lookup_location(request_location, 
+                                       YahooWeather::Units::CELSIUS)
+    _assert_valid_response(response, request_location, 
+                           YahooWeather::Units::CELSIUS, 
+                           city, region, country)
   end
-  
+
+  def test_lookup_by_woeid
+    woeid_sf = '12797168'
+    response = @client.lookup_by_woeid(woeid_sf)
+    _assert_valid_response(response, woeid_sf, 
+                           YahooWeather::Units::FAHRENHEIT,
+                           'San Francisco', 'CA', 'United States')
+  end
+
   private
 
-  def _assert_valid_response (response, request_location, units, city, region, country)
-    assert_not_nil response
-
-    # check the request location and url explicitly against what we know they should be
-    assert_equal response.request_location, request_location
-    assert_equal response.request_url, "http://xml.weather.yahoo.com/forecastrss?p=#{request_location}&u=#{units}"
-
-    # check the astronomy info
-    assert_instance_of YahooWeather::Astronomy, response.astronomy
-    assert_instance_of Time, response.astronomy.sunrise
-    assert_instance_of Time, response.astronomy.sunset
-    assert(response.astronomy.sunrise < response.astronomy.sunset)
-
-    # check the location
-    assert_instance_of YahooWeather::Location, response.location
-    assert_equal response.location.city, city
-    assert_equal response.location.region, region
-    assert_equal response.location.country, country
-
-    # check the default units
-    _assert_valid_units response.units, (units == 'f')
-
-    # check the wind info
-    assert_instance_of YahooWeather::Wind, response.wind
-    assert(response.wind.chill <= response.condition.temp)
-    assert_kind_of Numeric, response.wind.direction
-    assert_kind_of Numeric, response.wind.speed
-    
-    # check the atmosphere info
-    assert_instance_of YahooWeather::Atmosphere, response.atmosphere
-    assert_kind_of Numeric, response.atmosphere.humidity
-    assert_kind_of Numeric, response.atmosphere.visibility
-    assert_kind_of Numeric, response.atmosphere.pressure
-    assert(YahooWeather::Atmosphere::Barometer::ALL.include?(response.atmosphere.barometer))
-
-    # check the condition info
-    assert_instance_of YahooWeather::Condition, response.condition
-    _assert_valid_weather_code response.condition.code
-    assert_instance_of Time, response.condition.date
-    assert_kind_of Numeric, response.condition.temp
-    assert(response.condition.text && response.condition.text.length > 0)
-
-    # check the forecast info
-    assert_not_nil response.forecasts
-    assert_kind_of Array, response.forecasts
-    assert_equal response.forecasts.length, 2
-    response.forecasts.each do |forecast|
-      assert_instance_of YahooWeather::Forecast, forecast
-      assert(forecast.day && forecast.day.length == 3)
-      assert_instance_of Time, forecast.date
-      assert_kind_of Numeric, forecast.low
-      assert_kind_of Numeric, forecast.high
-      assert(forecast.low <= forecast.high)
-      assert(forecast.text && forecast.text.length > 0)
-      _assert_valid_weather_code forecast.code
+    def _assert_valid_response (response, request_location, units, 
+                                city, region, country)
+      assert_not_nil response
+
+      # check the request location and url explicitly against what we
+      # know they should be
+      assert_equal response.request_location, request_location
+      assert_match(/http:\/\/weather\.yahooapis\.com\/forecastrss\?[pw]=#{request_location}&u=#{units}/, response.request_url)
+
+      # check the astronomy info
+      assert_instance_of YahooWeather::Astronomy, response.astronomy
+      assert_instance_of Time, response.astronomy.sunrise
+      assert_instance_of Time, response.astronomy.sunset
+      assert(response.astronomy.sunrise < response.astronomy.sunset)
+
+      # check the location
+      assert_instance_of YahooWeather::Location, response.location
+      assert_equal response.location.city, city
+      assert_equal response.location.region, region
+      assert_equal response.location.country, country
+
+      # check the default units
+      _assert_valid_units(response.units, 
+                          (units == YahooWeather::Units::FAHRENHEIT))
+
+      # check the wind info
+      assert_instance_of YahooWeather::Wind, response.wind
+      assert(response.wind.chill <= response.condition.temp)
+      assert_kind_of Numeric, response.wind.direction
+      assert_kind_of Numeric, response.wind.speed
+
+      # check the atmosphere info
+      assert_instance_of YahooWeather::Atmosphere, response.atmosphere
+      assert_kind_of Numeric, response.atmosphere.humidity
+      assert_kind_of Numeric, response.atmosphere.visibility
+      assert_kind_of Numeric, response.atmosphere.pressure
+      assert(YahooWeather::Atmosphere::Barometer::ALL.include?(response.atmosphere.barometer))
+
+      # check the condition info
+      assert_instance_of YahooWeather::Condition, response.condition
+      _assert_valid_weather_code response.condition.code
+      assert_instance_of Time, response.condition.date
+      assert_kind_of Numeric, response.condition.temp
+      assert(response.condition.text && response.condition.text.length > 0)
+
+      # check the forecast info
+      assert_not_nil response.forecasts
+      assert_kind_of Array, response.forecasts
+      assert_equal response.forecasts.length, 2
+      response.forecasts.each do |forecast|
+        assert_instance_of YahooWeather::Forecast, forecast
+        assert(forecast.day && forecast.day.length == 3)
+        assert_instance_of Time, forecast.date
+        assert_kind_of Numeric, forecast.low
+        assert_kind_of Numeric, forecast.high
+        assert(forecast.low <= forecast.high)
+        assert(forecast.text && forecast.text.length > 0)
+        _assert_valid_weather_code forecast.code
+      end
+
+      # check the basic attributes
+      assert(response.description && response.description.length > 0)
+      assert(response.image.url =~ /yimg\.com/)
+      assert_kind_of Numeric, response.latitude
+      assert_kind_of Numeric, response.longitude
+      assert(response.page_url =~ /\.html$/)
+      assert(response.title && response.title.length > 0)
+      assert_not_nil(response.title.index("#{response.location.city}, #{response.location.region}"))
     end
-    
-    # check the basic attributes
-    assert(response.description && response.description.length > 0)
-    assert(response.image_url =~ /yimg\.com/)
-    assert_kind_of Numeric, response.latitude
-    assert_kind_of Numeric, response.longitude
-    assert(response.page_url =~ /\.html$/)
-    assert(response.title && response.title.length > 0)
-    assert_not_nil (response.title.index("#{response.location.city}, #{response.location.region}"))
-  end
-    
-  def _assert_valid_weather_code (code)
-    (((code >= 0) && (code <= 47)) || (code == 3200))
-  end
-  
-  def _assert_valid_units (units, fahrenheit_based)
-    assert_instance_of YahooWeather::Units, units
-    if fahrenheit_based
-      assert_equal units.temperature, 'F'
-      assert_equal units.distance, 'mi'
-      assert_equal units.pressure, 'in'
-      assert_equal units.speed, 'mph'
-
-    else
-      assert_equal units.temperature, 'C'
-      assert_equal units.distance, 'km'
-      assert_equal units.pressure, 'mb'
-      assert_equal units.speed, 'kph'
+
+    def _assert_valid_weather_code (code)
+      (((code >= 0) && (code <= 47)) || (code == 3200))
     end
-  end
+
+    def _assert_valid_units (units, fahrenheit_based)
+      assert_instance_of YahooWeather::Units, units
+      if fahrenheit_based
+        assert_equal units.temperature, 'F'
+        assert_equal units.distance, 'mi'
+        assert_equal units.pressure, 'in'
+        assert_equal units.speed, 'mph'
+
+      else
+        assert_equal units.temperature, 'C'
+        assert_equal units.distance, 'km'
+        assert_equal units.pressure, 'mb'
+        assert_equal units.speed, 'km/h'
+      end
+    end
+
 end