barometer 0.7.0 → 0.7.1

data/lib/demometer/views/readme.erb

@@ -1,453 +0,0 @@
-<h1>barometer</h1>
-<p>
-A multi API consuming weather forecasting superstar.
-</p>
-<p>
-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.
-</p>
-<p>
-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&#8217;t
-support the query directly. See the &quot;Query&quot; section for more
-information on this.
-</p>
-<h2>version</h2>
-<p>
-Version 0.6.3 is the current release of this gem. The gem is available from
-github (attack-barometer) or rubyforge (barometer). It is fully functional
-(for five 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, weather.com, weather_bug).
-</p>
-<p>
-Features to be added next:
-</p>
-<ul>
-<li>even more weather service drivers (noaa)
-
-</li>
-<li>icon support
-
-</li>
-</ul>
-<h1>dependencies</h1>
-<h2>Google API key</h2>
-<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 &#8217;~/.barometer&#8217; by adding the lines:
-</p>
-<pre>
-  google:
-    geocode: YOUR_KEY_HERE
-</pre>
-<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&#8217;t require any geocoding)
-
-</li>
-<li>running the Barometer binary
-
-</li>
-<li>running the Barometer Web Demo
-
-</li>
-</ul>
-<h3>other keys</h3>
-<p>
-The same file can hold all your weather service API keys.
-</p>
-<p>
-eg. weather.com
-</p>
-<pre>
-  weather:
-    partner: YOUR_PARTNER_KEY
-    license: YOUR_LICENSE_KEY
-</pre>
-<p>
-eg. weatherbug.com
-</p>
-<pre>
-  weather_bug:
-    code: YOUR_API_CODE
-</pre>
-<h2>HTTParty</h2>
-<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.
-</p>
-<p>
-HTTParty is also extended to include configurable Timeout support.
-</p>
-<h2>tzinfo</h2>
-<p>
-Why? Barometer deals with time information for locations all over the
-world. This information doesn&#8217;t mean that much if it can&#8217;t be
-converted to times that don&#8217;t correspond to the applicable timezone.
-Tzinfo handles this time zone manipulation.
-</p>
-<h1>queries</h1>
-<p>
-The query handling is one of the most beneficial and powerful features of
-Barometer. Every weather service accepts a different set of possible
-queries, so it usually the case that the same query can only be used for a
-couple weather services.
-</p>
-<p>
-Barometer will allow the use of all query formats for all services
-(mostly). It does this by first determining the original query format, then
-converting the query to a compatible format for each specific weather
-service.
-</p>
-<p>
-For example, Yahoo! only accepts US Zip Code or Weather.com ID. With
-Barometer you can query Yahoo! with a simple location (ie: Paris) or even
-an Airport code (ICAO) and it will return the weather as expected.
-</p>
-<h2>acceptable formats</h2>
-<ul>
-<li>zipcode
-
-</li>
-<li>icao (international airport code)
-
-</li>
-<li>coordinates (latitude and longitude)
-
-</li>
-<li>postal code
-
-</li>
-<li>weather.com ID
-
-</li>
-<li>location name (ie address, city, state, landmark, etc.)
-
-</li>
-<li>if the query is of the formats zipcode or postal code it may not support
-conversion to other formats.
-
-</li>
-</ul>
-<h2>conversion caching</h2>
-<p>
-Barometer has internal conversion caching. No conversion will be repeated
-during a measurement, thus limiting the number of web queries needed.
-</p>
-<p>
-Example: If you configure Barometer to use both Yahoo and Weather.com, then
-use a query like &quot;denver&quot;, this will require a conversion from
-&quot;denver&quot; to its weather.com weather_id. This conversion is needed
-for both web services but will only happen once and be cached.
-</p>
-<h1>usage</h1>
-<p>
-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).
-</p>
-<p>
-For better results, signup for a google-map key and enhance your barometer
-with geo-coding.
-</p>
-<pre>
-  require 'barometer'
-
-  Barometer.google_geocode_key = &quot;THE_GOOGLE_API_KEY&quot;
-  barometer = Barometer.new(&quot;Paris&quot;)
-  weather = barometer.measure
-
-  puts weather.current.temperture
-</pre>
-<h2>sources</h2>
-<p>
-The available sources are:
-</p>
-<pre>
-  Wunderground.com (:wunderground) [default]
-  Yahoo! Weather (:yahoo)
-  Google Weather (:google)
-  Weather.com (:weather_dot_com)
-  WeatherBug.com (:weather_bug)
-</pre>
-<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 =&gt; [:yahoo, :google] }
-</pre>
-<p>
-Weather services in primary/failover
-</p>
-<pre>
-  Barometer.config = { 1 =&gt; [:yahoo], 2 =&gt; :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 =&gt; [{:wunderground =&gt; {:weight =&gt; 2}}, :google] }
-</pre>
-<p>
-Weather services, one with keys.
-</p>
-<pre>
-  Barometer.config = { 1 =&gt; [:yahoo, {:weather_dot_com =&gt; {:keys =&gt; {:partner =&gt; PARTNER_KEY, :license =&gt; LICENSE_KEY } }}] }
-</pre>
-<h3>multiple weather API, with hierarchy</h3>
-<pre>
-  require 'barometer'
-
-  Barometer.google_geocode_key = &quot;THE_GOOGLE_API_KEY&quot;
-  # use yahoo and google, if they both fail, use wunderground
-  Barometer.config = { 1 =&gt; [:yahoo, :google], 2 =&gt; :wunderground }
-
-  barometer = Barometer.new(&quot;Paris&quot;)
-  weather = barometer.measure
-
-  puts weather.current.temperture
-</pre>
-<h2>command line</h2>
-<p>
-You can use barometer from the command line.
-</p>
-<pre>
-  # barometer berlin
-</pre>
-<p>
-This will output the weather information for the given query. See the help
-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 &quot;sinatra&quot; and &quot;vegas&quot;.
-</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,
-or providing a query for a location not supported by the weather service.
-</p>
-<p>
-For example, if you look at the example above, the query of
-&quot;Paris&quot; 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).
-</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>
-<h3>by preference (default service)</h3>
-<pre>
-  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
-</pre>
-<h3>by source</h3>
-<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(&quot;01-01-2009&quot;)
-  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
-</pre>
-<h3>by time</h3>
-<pre>
-  # note, the time is the time of the locations weather, not the time of the
-  # user measuring the weather
-  time = Time.parse(&quot;13:00 01-01-2009&quot;)
-  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 &#8216;current&#8217;
-values and not the forecasted values).
-</p>
-<pre>
-  require 'barometer'
-
-  Barometer.google_geocode_key = &quot;THE_GOOGLE_API_KEY&quot;
-  # use yahoo and wunderground
-  Barometer.config = { 1 =&gt; [:yahoo, :wunderground] }
-
-  barometer = Barometer.new(&quot;90210&quot;)
-  weather = barometer.measure
-
-  puts weather.temperture
-</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 &#8230; see the config section
-</p>
-<h2>simple answers</h2>
-<p>
-After you have measured the data, Barometer provides several &quot;simple
-answer&quot; 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
-
-  weather.windy?(10)
-</pre>
-<h3>is it wet?</h3>
-<pre>
-  # 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)
-</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?
-</pre>
-<h3>is it night?</h3>
-<pre>
-  # 1st parameter is the utc_time for which you want to know the answer,
-  #   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 conversion if weather service accepts this directly)
-
-</li>
-<li>postal code (skips conversion if weather service accepts this directly)
-
-</li>
-<li>latitude and longitude (skips conversion if weather service accepts this
-directly)
-
-</li>
-<li>weather.com weather id (even if the service you are using doesn&#8217;t use
-it)
-
-</li>
-<li>international airport code (skips conversion if weather service accepts
-this directly)
-
-</li>
-</ul>
-</li>
-<li>determine which weather services will be queried (one or multiple)
-
-</li>
-<li>if query conversion required for specific weather service, convert the
-query
-
-</li>
-<li>query the weather services
-
-</li>
-<li>save the data
-
-</li>
-<li>repeat weather service queries as needed
-
-</li>
-</ul>
-<h1>extending</h1>
-<p>
-Barometer attempts to be a common API to any weather service API. I have
-included several weather service &#8216;drivers&#8217;, but I know there
-are many more available. Please use the provided ones as examples to create
-more.
-</p>
-<h2>copyright</h2>
-<p>
-Copyright &#169; 2009 Mark G. See LICENSE for details.
-</p>