barometer

A multi API consuming weather forecasting superstar.

Barometer provides a common public API to one or more weather services (APIs) of your choice. Weather services can co-exist to retrieve extensive information, or they can be used in a hierarchical configuration where lower preferred weather services are only used if previous services are unavailable.

Barometer handles all conversions of the supplied query, so that the same query can be used for all (or most) services, even if they don’t support the query directly.

For example, Yahoo! only accepts US Zip Code or Weather.com ID. With Barometer you can query Yahoo! with a simple location (ie: Paris) and it will return the weather.

version

Version 0.5.0 is the current release of this gem. The gem is available from github (attack-barometer) or rubyforge (barometer). It is fully functional (for four weather service APIs).

status

Currently this project is in development and will only work for a few weather services (wunderground, google, yahoo, weather.com).

Features to be added next:

even more weather service drivers (noaa, weatherbug)
icon support

dependencies

Google API key

In most cases you will need to have a free google geocode api key. Get one here: code.google.com/apis/maps/signup.html Then put it in the file ‘~/.barometer’ by adding the lines:

google:
  geocode: YOUR_KEY_HERE

You will need this for:

using the Barometer gem (unless you use queries that are directly supported by the weather source API, ie yahoo will take a zip code directly and doesn’t require any geocoding)
running the Barometer binary
running the Barometer Web Demo

other keys

The same file can hold all your weather service API keys.

eg. weather.com

weather:
  partner: YOUR_PARTNER_KEY
  license: YOUR_LICENSE_KEY

HTTParty

Why? HTTParty was created and designed specifically for consuming web services. I choose to use this over using the Net::HTTP library directly to allow for faster development of this project.

HTTParty is also extended to include configurable Timeout support.

tzinfo

Why? Barometer deals with time information for locations all over the world. This information doesn’t mean that much if it can’t be converted to times that don’t correspond to the applicable timezone. Tzinfo handles this time zone manipulation.

usage

You can use barometer right out of the box, as it is configured to use one register-less (no API key required) international weather service (wunderground.com).

For better results, signup for a google-map key and enhance your barometer with geo-coding.

require 'barometer'

Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
barometer = Barometer.new("Paris")
weather = barometer.measure

puts weather.current.temperture

sources

The available sources are:

Wunderground.com (:wunderground) [default]
Yahoo! Weather (:yahoo)
Google Weather (:google)
Weather.com (:weather_dot_com)

source configuration

Barometer can be configured to use multiple weather service APIs (either in a primary/failover config or in parallel). Each weather service can also have its own config.

Weather services in parallel

Barometer.config = { 1 => [:yahoo, :google] }

Weather services in primary/failover

Barometer.config = { 1 => [:yahoo], 2 => :wunderground }

Weather services, one with some configuration. In this case we are setting a weight value, this weight is respected when calculating averages.

Barometer.config = { 1 => [{:wunderground => {:weight => 2}}, :google] }

Weather services, one with keys.

Barometer.config = { 1 => [:yahoo, {:weather_dot_com => {:keys => {:partner => PARTNER_KEY, :license => LICENSE_KEY } }}] }

multiple weather API, with hierarchy

require 'barometer'

Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
# use yahoo and google, if they both fail, use wunderground
Barometer.config = { 1 => [:yahoo, :google], 2 => :wunderground }

barometer = Barometer.new("Paris")
weather = barometer.measure

puts weather.current.temperture

command line

You can use barometer from the command line.

# barometer berlin

This will output the weather information for the given query. See the help for more command line information.

# barometer -h

web demo

There is a Sinatra application that demos the functionality of Barometer, and provides Barometer information. Start this local demo with:

# barometer -w

NOTE: This requires the gems “sinatra” and “vegas”.

fail

What would cause a weather service to fail? The most obvious is that the particular weather service in currently unavailable or not reachable. Other possible reasons would include not having the API (or a valid API key for the particular weather service, if required), not providing a valid query, or providing a query for a location not supported by the weather service.

For example, if you look at the example above, the query of “Paris” refers to a city in France. Yahoo weather services only supports weather results for USA (at least at the time of writing). Therefore, Barometer would not use Yahoo, just Google and failover to use Wunderground (if needed).

searching

After you have measured the data, Barometer provides several methods to help you get the data you are after. All examples assume you already have measured the data as shown in the above examples.

by preference (default service)

weather.default         # returns measurement for default source
weather.current         # returns current_measurement for default
weather.now             # returns current_measurement for default
weather.forecast        # returns all forecast_measurements for default
weather.today           # returns forecast_measurement for default today
weather.tomorrow        # returns forecast_measurement for default tomorrow

puts weather.now.temperature.c
puts weather.tomorrow.high.c

by source

weather.source(:wunderground)   # returns measurement for specified source
weather.sources                 # lists all successful sources

puts weather.source(:wunderground).current.temperature.c

by date

# note, the date is the date of the locations weather, not the date of the
# user measuring the weather
date = Date.parse("01-01-2009")
weather.for(date)       # returns forecast_measurement for default on date 
weather.source(:wunderground).for(date)   # same as above but specific source

puts weather.source(:wunderground).for(date).high.c

by time

# note, the time is the time of the locations weather, not the time of the
# user measuring the weather
time = Time.parse("13:00 01-01-2009")
weather.for(time)       # returns forecast_measurement for default at time 
weather.source(:wunderground).for(time)   # same as above but specific source

puts weather.source(:wunderground).for(time).low.f

averages

If you consume more then one weather service, Barometer can provide averages for the values (currently only for the ‘current’ values and not the forecasted values).

require 'barometer'

Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
# use yahoo and wunderground
Barometer.config = { 1 => [:yahoo, :wunderground] }

barometer = Barometer.new("90210")
weather = barometer.measure

puts weather.temperture

This will calculate the average temperature as given by :yahoo and :wunderground

weights

You can weight the values from a weather service so that the values from that web service have more influence then other values. The weights are set in the config … see the config section

simple answers

After you have measured the data, Barometer provides several “simple answer” methods to help you get answers to some basic questions. All examples assume you already have measured the data as shown in the above examples.

All of these questions are ultimately specific to the weather source(s) you are configured to use. All sources that have successfully measured data will be asked, but if there is no data that can answer the question then there will be no answer.

is it windy?

# 1st parameter is the threshold wind speed for being windy
# 2nd parameter is the utc_time for which you want to know the answer,
#   this defaults to the current time
# NOTE: in my example the values are metric, so the threshold is 10 kph

weather.windy?(10)

is it wet?

# 1st parameter is the threshold pop (%) for being wet
# 2nd parameter is the utc_time for which you want to know the answer,
#   this defaults to the current time
# NOTE: in my example the threshold is 50 %

weather.wet?(50)

is it sunny?

# 1st parameter is the utc_time for which you want to know the answer,
#   this defaults to the current time

weather.sunny?

is it day?

# 1st parameter is the utc_time for which you want to know the answer,
#   this defaults to the current time

weather.day?

is it night?

# 1st parameter is the utc_time for which you want to know the answer,
#   this defaults to the current time

weather.night?

design

create a Barometer instance
supply a query, there are very little restrictions on the format:
- city, country, specific address (basically anything Google will geocode)
- US zip code (skips conversion if weather service accepts this directly)
- postal code (skips conversion if weather service accepts this directly)
- latitude and longitude (skips conversion if weather service accepts this directly)
- weather.com weather id (even if the service you are using doesn’t use it)
- international airport code (skips conversion if weather service accepts this directly)
determine which weather services will be queried (one or multiple)
if query conversion required for specific weather service, convert the query
query the weather services
save the data
repeat weather service queries as needed

extending

Barometer attempts to be a common API to any weather service API. I have included several weather service ‘drivers’, but I know there are many more available. Please use the provided ones as examples to create more.