barometer 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mark
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,266 @@
+= 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.
+
+== status
+
+Currently this project is in development and will only work for a few weather
+services (wunderground, google, yahoo).
+
+Features to be added before first release:
+- gem setup/config, apply to rubyforge
+
+Features to be added in future releases:
+- even more weather service drivers (noaa, weather.com, weatherbug)
+- ability to query multiple services and combine/average the results
+- support iaco as a query format
+
+= dependencies
+
+=== 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 Timoout 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.
+
+=== graticule (very soft dependency)
+
+Why? Barometer returns the weather for a given location.  Most weather service
+APIs are somewhat restricted on the query format they receive.  To bridge
+this gap and allow for maximum flexibility on the 'barometer' query format,
+the query will be geo-coded using the Google geocoding service, if required.
+Graticule can provide this geocoding interface.
+
+Using Graticule requires a free Google API key for geocoding.  It is possible
+to use barometer without geocoding, though your query format will be
+limited to that of the weather service API.
+
+ALTERNATE: If you supply a Google API key but don't install the Graticule gem,
+HTTParty will be used instead to provide the same geocoding.  Basically
+Graticule is only used if it exists.
+
+NOTE: you can force Barometer not to use Graticule, even if you have it installed
+using the following:
+
+  Barometer.skip_graticule = true
+
+= 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
+  
+== 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.selection = { 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.
+  
+=== 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).
+
+=== bootstrapping
+
+You can use weather service drivers directly.  Below is an example to use
+Wunderground, but since the driver interface is abstracted it will be the
+same for all supported services.
+
+  require 'barometer'
+  Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
+  
+  query = Barometer::Query.new("Paris")
+  weather = Barometer::Service.source(:wunderground).measure(query)
+  
+  puts weather.current.temperture
+  
+  # OR, even more raw
+  
+  measurement = Barometer::Measurement.new
+  weather = Barometer::Wunderground.measure_all(measurement, "Paris")
+  
+  puts weather.current.temperture
+  
+  
+NOTE: The disadvantage to using the drivers directly is that you lose the
+advantage of redundancy/failover added by the Module as a whole.
+
+NOTE: You still must create the Barometer::Query object with your query
+string instead of directly feeding the query string to the service (as in
+bootstrap example #1).  The Barometer::Query object has behavior required
+by the service that a regular String doesn't have. Using a driver directly
+WILL accept a String (as in bootstrap example #2).
+
+== 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
+  
+== 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 geocoding if weather service accepts this directly)
+  - postal code (skips geocoding if weather service accepts this directly)
+  - latitude and longitude (skips geocoding if weather service accepts this
+    directly)
+  - TODO: international airport code (skips geocoding if weather service
+    accepts this directly)
+- if geocoding required, geocode the query
+- determine which weather services will be queried (one or multiple)
+- 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.
+
+== copyright
+
+Copyright (c) 2009 Mark G. See LICENSE for details.

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:major: 0
+:minor: 1
+:patch: 0

data/bin/barometer

@@ -0,0 +1,63 @@
+#!/usr/bin/env ruby
+ 
+require File.dirname(__FILE__) + '/../lib/barometer'
+#require 'rubygems'
+#require 'attack-barometer'
+
+# TODO
+
+# set default Google Key ... maybe need a config file?
+Barometer.google_geocode_key = "ABQIAAAAq8TH4offRcGrok8JVY_MyxRi_j0U6kJrkFvY4-OX2XYmEAa76BSFwMlSow1YgX8BOPUeve_shMG7xw"
+
+# take command line paramters
+# service: --yahoo, --wunderground, --google
+# units: -m --metric, -i --imperial
+# geocode: -g --geocode (force geocode)
+# timeout: -t 15 --timeout 15
+# skip: --skip (skip graticule)
+# help: -h --help
+# wet threshold: -w --wet
+# windy threshold: -v --wind
+# pop threshold: -p --pop
+# time: -a --at
+
+# prettier output
+# show simple answers
+# more help
+# error display (out of sources, etc.)
+ 
+if ARGV.size == 0
+  puts 'Barometer [Powered by wunderground]'
+  puts 'USAGE: barometer [query]'
+  puts 'EXAMPLES:'
+  puts ' barometer paris'
+  exit
+end
+ 
+barometer = Barometer.new(ARGV[0])
+weather = barometer.measure(true)
+
+def y(value)
+  value ? "yes" : "no"
+end
+
+if weather
+  puts "###################################################"
+  puts "#  #{weather.default.location.name}"
+  puts "#"
+  puts "#  (lat: #{weather.default.location.latitude}, long: #{weather.default.location.longitude})"
+  puts "###################################################"
+  puts " -- CURRENT --"
+  puts " temperature: #{weather.now.temperature}"
+  puts
+  puts " -- QUESTIONS --"
+  puts " day?  : #{y(weather.day?)}"
+  puts " sunny?: #{y(weather.sunny?)}"
+  puts " windy?: #{y(weather.windy?)}"
+  puts " wet?  : #{y(weather.wet?)}"
+  puts
+  puts
+  puts " -- INFO --"
+  puts " http://github.com/attack/barometer"
+  puts "---------------------------------------------------"
+end

data/lib/barometer.rb

@@ -0,0 +1,52 @@
+$:.unshift(File.dirname(__FILE__))
+
+require 'barometer/base'
+require 'barometer/query'
+require 'barometer/weather'
+require 'barometer/services'
+require 'barometer/data'
+ 
+module Barometer
+  
+  @@google_geocode_key = nil
+  def self.google_geocode_key; @@google_geocode_key; end;
+  def self.google_geocode_key=(key); @@google_geocode_key = key; end;
+  
+  @@skip_graticule = false
+  def self.skip_graticule; @@skip_graticule; end;
+  def self.skip_graticule=(value); @@skip_graticule = value; end;
+  
+  # sometimes a query is used as is and never gets geocoded (ie zipcode)
+  # often, it is useful have queries geocoded to know where in the
+  # world that query points to.  you can force the geocoding of
+  # queries (even when not required) so that you have the geocoded
+  # data.  the reason this isn't the default is that it will use an
+  # extra web service query when not normally required
+  @@force_geocode = false
+  def self.force_geocode; @@force_geocode; end;
+  def self.force_geocode=(value); @@force_geocode = value; end;
+  def self.force_geocode!; @@force_geocode = true; end;
+  
+  @@timeout = 15
+  def self.timeout; @@timeout; end;
+  def self.timeout=(value); @@timeout = value; end;
+  
+  def self.new(query=nil)
+    Barometer::Base.new(query)
+  end
+  
+  def self.selection=(selection=nil)
+    Barometer::Base.selection = selection
+  end
+  
+  # shortcut to Barometer::Service.source method
+  # allows Barometer.source(:wunderground)
+  def self.source(source)
+    Barometer::Service.source(source)
+  end
+
+  # custom errors
+  class OutOfSources < StandardError; end
+  
+end
+

data/lib/barometer/base.rb

@@ -0,0 +1,52 @@
+module Barometer
+
+  class Base
+    
+    # allow the configuration of specific weather APIs to be used,
+    # and the order in which they would be used
+    @@selection = { 1 => [:wunderground] }
+    def self.selection; @@selection; end;
+    def self.selection=(hash); @@selection = hash; end;
+    
+    attr_reader   :query
+    attr_accessor :weather, :success
+    
+    def initialize(query=nil)
+      @query = Barometer::Query.new(query)
+      @weather = Barometer::Weather.new
+      @success = false
+    end
+    
+    def measure(metric=nil)
+      return nil unless @query
+
+      level = 1
+      until self.success?
+        if sources = @@selection[level]
+          if sources.is_a?(Array)
+            sources.each do |source|
+              measurement = Barometer.source(source.to_sym).measure(@query, metric)
+              @success = true if measurement.success?
+              @weather.measurements << measurement
+            end
+          else  
+            measurement = Barometer.source(sources.to_sym).measure(@query, metric)
+            @success = true if measurement.success?
+            @weather.measurements << measurement
+          end
+        else
+          raise OutOfSources
+        end
+        level += 1
+      end
+      
+      @weather
+    end
+    
+    def success?
+      @success
+    end
+
+  end
+
+end