RubyWeather

Author: Matt Zukowski (blog.roughest.net)
Copyright: Copyright © 2006 Urbacon Ltd.
License: GNU Lesser General Public License v2.1 (LGPL 2.1)

RubyWeather is a Ruby[http://ruby-lang.org] library for fetching weather-related data from weather.com[http://www.weather.com/services/xmloap.html].

Download & Install

You can download the latest stable version of RubyWeather from rubyforge.org/projects/rubyweather or install as a RubyGem:

sudo gem install rubyweather

You can also check out the latest copy via subversion from rubyweather.googlecode.com/svn/trunk/. If you would like to contribute back your changes to the code, please contact me via the RubyForge or Google Code project site to obtain a subversion account.

RubyWeather can also be installed as a Rails plugin using the following command from your Rails application’s directory:

./script/plugin install -x http://rubyweather.googlecode.com/svn/trunk

Examples

First, we need to find out the weather.com location code for your city. The following code will print out a list of locations and their codes matching the string “Toronto”:

require 'rubygems'
require_gem 'rubyweather'

require 'weather/service'

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

We can now use the code 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 forecast.day(#) where # is the number of days into the future (assuming that you’ve fetched data for as many days in your service.fetch_forecast 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

Nighttime data is also available via forecast.night(#):

puts "Probability of precipitation three nights from now: %s" % forecast.night(3).pop

There are a lot of attributes you can fetch for a forecast. Here are just a few:

temp, temperature: The temperature. For future days this is equivalent to the low for nighttime, and high for daytime.
icon: The number of the icon gif file from the weather.com SDK that identifies the conditions (e.g. a little icon of a cloud with rain, or sun, or whatever).
outlook: Brief text describing the conditions (e.g. “Mostly Cloudy”, “Rain”, “Scattered T-Storms”).
outlook_brief: An abbreviated version of outlook (e.g. “M Cloudy”, “Scat T-Storms”).
low, lo: The forecasted low temperature. (Not available for current conditions)
high, hi: The forecasted high temperature. (Not available for current conditions)
wind: Wind conditions. The wind attribute returns an object with sub-attributes that can be addressed like wind.direction, wind.speed, wind.heading, etc.
pop, ppcp: Probability of precipitation.
date: The date that this forecast is for, returned as a ruby Time object.
sunrise: The time of sunrise on the day of the forecast.
sunset: The time of sunset on the day of the forecast.
latest_update: The datetime when the conditions were last measured/forecast.

Additionally, most of the attributes for a given day in the raw weather.com xml data are also directly accessible. For example, you can call forecast.tomorrow.dewp to get the dewpoint, because the xml file contains a dewp 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 element values will be returned as a string, \ without any nice class casting or unit conversion.

Other programmers are encouraged to add more functionality to the lib/forecast.rb module to provide better accessor methods for the underlying xml data. See below for how to obtain subversion access to contribute your changes back to the project.

Caching Forecast Data

RubyWeather supports data caching using the memcached daemon. This allows for much quicker response time – especially if you have a lot of clients accessing the weather data – and it’s just a polite thing to do in regards to weather.com’s servers.

If you have a memcached server running, you can turn on data caching as follows:

s = Weather::Service.new
s.enable_cache
s.cache_expiry = 60  # cached data will expire after 60 seconds; if omitted, the default is 10 minutes
s.cache.servers = ['127.0.0.1:11211']

From now on, any fetch_forecast calls made on this service will cache their data. This means that the weather.com server will not be queried again as long as the data is cached.

You can check if a forecast came from the cache by calling #from_cache?, which returns true if this forecast came from the local cache. You can also call #cached_on to find out when this forecast was entered into the cache or nil if the forecast didn’t come from the cache.

The above requires that a ruby memcache client be installed. RubyWeather has been tested with the memcache-client and Ruby-MemCache. memcache-client is much faster, so you’re probably better off using it over Ruby-MemCache:

gem install memcache-client

Sample Rails Controller

In the example directory you will find a sample Rails controller that uses RubyWeather to show a simple weather forecast. To try this out:

Copy the controller into your Rails app’s app/controllers/.
Copy the forecast.rhtml template into apps/view/weather_portlet/
Copy weather_32 into public/images/.

Fire up your Rails server, and go to /weather_portlet/forecast to see the controller in action.

Note About Weather.com Licensing & Registration

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, asks that 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 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.

Note that weather.com doesn’t seem to be enforcing the partner id/license key at this time. You can specify any value for partner id and license key (e.g. par=123456&key=abcdefg) and the weather.com service will happily accept it (in fact, you can even leave both fields blank, i.e. part=&key=). However, this is probably unintentional and subject to change, so it is highly recommended that you obtain a valid id and key.

Software 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