lib/demometer/views/readme.erb in attack-barometer-0.3.2 vs lib/demometer/views/readme.erb in attack-barometer-0.5.0
- old
+ new
@@ -9,16 +9,16 @@
lower preferred weather services are only used if previous services are
unavailable.
</p>
<h2>version</h2>
<p>
-
-Version 0.3.1 is the current release of this gem. The gem is available from
+Version 0.3.3 is the current release of this gem. The gem is available from
github (attack-barometer) or rubyforge (barometer). It is fully functional
(for three weather service APIs).
</p>
<h2>status</h2>
+
<p>
Currently this project is in development and will only work for a few
weather services (wunderground, google, yahoo).
</p>
<p>
@@ -29,27 +29,34 @@
</li>
</ul>
<h1>dependencies</h1>
<h3>Google API key</h3>
-
<p>
In most cases you will need to have a free google geocode api key. Get one
here: <a href="http://code.google.com/apis/maps/signup.html">code.google.com/apis/maps/signup.html</a>
+
Then put it in the file ’~/.barometer’ by adding the line:
geocode_google: YOUR_KEY_HERE
</p>
<p>
You will need this for:
</p>
<ul>
<li>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)</li>
-<li>running the Barometer binary</li>
-<li>running the Barometer Web Demo</li>
+doesn’t require any geocoding)
+
+</li>
+<li>running the Barometer binary
+
+</li>
+<li>running the Barometer Web Demo
+
+</li>
</ul>
+
<h3>HTTParty</h3>
<p>
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.
@@ -61,13 +68,13 @@
<p>
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.
-
</p>
<h3>graticule (very soft dependency)</h3>
+
<p>
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
@@ -83,15 +90,15 @@
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.
</p>
<p>
-
NOTE: you can force Barometer not to use Graticule, even if you have it
installed using the following:
</p>
<pre>
+
Barometer.skip_graticule = true
</pre>
<h1>usage</h1>
<p>
You can use barometer right out of the box, as it is configured to use one
@@ -104,30 +111,57 @@
</p>
<pre>
require 'barometer'
Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
-
barometer = Barometer.new("Paris")
weather = barometer.measure
puts weather.current.temperture
+
</pre>
-<h2>multiple weather API, with hierarchy</h2>
+<h2>source configuration</h2>
+<p>
+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.
+</p>
+<p>
+Weather services in parallel
+</p>
<pre>
+ Barometer.config = { 1 => [:yahoo, :google] }
+</pre>
+<p>
+Weather services in primary/failover
+
+</p>
+<pre>
+ Barometer.config = { 1 => [:yahoo], 2 => :wunderground }
+</pre>
+<p>
+Weather services, one with some configuration. In this case we are setting
+a weight value, this weight is respected when calculating averages.
+</p>
+<pre>
+ Barometer.config = { 1 => [{:wunderground => {:weight => 2}}, :google] }
+
+</pre>
+<h3>multiple weather API, with hierarchy</h3>
+<pre>
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.config = { 1 => [:yahoo, :google], 2 => :wunderground }
barometer = Barometer.new("Paris")
weather = barometer.measure
puts weather.current.temperture
-
</pre>
+
<h2>command line</h2>
<p>
You can use barometer from the command line.
</p>
<pre>
@@ -138,24 +172,24 @@
for more command line information.
</p>
<pre>
# barometer -h
</pre>
-
<h3>web demo</h3>
+
<p>
There is a Sinatra application that demos the functionality of Barometer,
and provides Barometer information. Start this local demo with:
</p>
<pre>
# barometer -w
</pre>
<p>
NOTE: This requires the gems "sinatra" and "vegas".
</p>
-
<h3>fail</h3>
+
<p>
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,
@@ -173,11 +207,10 @@
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.
</p>
<pre>
-
require 'barometer'
Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
query = Barometer::Query.new("Paris")
weather = Barometer::Service.source(:wunderground).measure(query)
@@ -199,13 +232,13 @@
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).
-
</p>
<h2>searching</h2>
+
<p>
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.
</p>
@@ -225,12 +258,12 @@
<pre>
weather.source(:wunderground) # returns measurement for specified source
weather.sources # lists all successful sources
puts weather.source(:wunderground).current.temperature.c
-
</pre>
+
<h3>by date</h3>
<pre>
# 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")
@@ -246,24 +279,24 @@
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
-
</pre>
<h2>averages</h2>
+
<p>
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).
</p>
<pre>
require 'barometer'
Barometer.google_geocode_key = "THE_GOOGLE_API_KEY"
# use yahoo and wunderground
- Barometer.selection = { 1 => [:yahoo, :wunderground] }
+ Barometer.config = { 1 => [:yahoo, :wunderground] }
barometer = Barometer.new("90210")
weather = barometer.measure
puts weather.temperture
@@ -271,25 +304,31 @@
</pre>
<p>
This will calculate the average temperature as given by :yahoo and
:wunderground
</p>
+<h3>weights</h3>
+<p>
+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
+</p>
<h2>simple answers</h2>
<p>
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.
+
</p>
<p>
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.
</p>
<h3>is it windy?</h3>
-
<pre>
# 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
@@ -304,18 +343,18 @@
# NOTE: in my example the threshold is 50 %
weather.wet?(50)
</pre>
<h3>is it sunny?</h3>
+
<pre>
# 1st parameter is the utc_time for which you want to know the answer,
# this defaults to the current time
weather.sunny?
</pre>
<h3>is it day?</h3>
-
<pre>
# 1st parameter is the utc_time for which you want to know the answer,
# this defaults to the current time
weather.day?
@@ -326,18 +365,18 @@
# this defaults to the current time
weather.night?
</pre>
<h1>design</h1>
+
<ul>
<li>create a Barometer instance
</li>
<li>supply a query, there are very little restrictions on the format:
<ul>
-
<li>city, country, specific address (basically anything Google will geocode)
</li>
<li>US zip code (skips geocoding if weather service accepts this directly)
@@ -353,19 +392,19 @@
accepts this directly)
</li>
</ul>
</li>
+
<li>if geocoding required, geocode the query
</li>
<li>determine which weather services will be queried (one or multiple)
</li>
<li>query the weather services
-
</li>
<li>save the data
</li>
<li>repeat weather service queries as needed
@@ -376,11 +415,11 @@
<p>
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.
+
</p>
<h2>copyright</h2>
<p>
Copyright © 2009 Mark G. See LICENSE for details.
-
</p>