English
资源说明：Ruby library for accessing forecast data from weather.com
= 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)
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 http://rubyforge.org/projects/rubyweather
or install as a RubyGem:
sudo gem install rubyweather
You can also check out the latest copy via subversion from http://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
== Obtaining a Free Weather.com License
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 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.
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.
=== Examples
First, we need to find the weather.com location code for your city.
The following Ruby code will print out a list of locations and their codes
matching the string "Toronto":
require 'rubygems'
gem 'rubyweather'
require 'weather/service'
service = Weather::Service.new
service.partner_id = your partner id
service.license_key = your license key
locations = service.find_location('Toronto')
puts "Matching Locations: " + locations.inspect
We can now use location 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[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).
+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[http://www.danga.com/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[http://dev.robotcoop.com/Libraries/memcache-client/index.html] and
Ruby-MemCache[http://www.deveiate.org/projects/RMemCache]. 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:
1. Copy the controller into your Rails app's app/controllers/.
2. Copy the forecast.rhtml template into apps/view/weather_portlet/
3. Copy weather_32 into public/images/.
Fire up your Rails server, and go to /weather_portlet/forecast to see the controller in action.
== 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
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
