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].
Simple usage example:
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
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 forecast.day(#)
where #
is the number of day sinto 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
There are a lot of attributes you can fetch for a forecast day. 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 likewind.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 elements 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.
Download
You can download the latest stable version of RubyWeather from rubyforge.org/projects/rubyweather/.
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.
RubyWeather can also be installed as a Rails plugin using the following command from your Rails application’s directory:
./script/plugin install -x svn://rubyforge.org//var/svn/rubyweather/trunk
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 intoapps/view/weather_portlet/
-
Copy
weather_32
intopublic/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