barometer 0.7.0 → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,453 +0,0 @@
1
- <h1>barometer</h1>
2
- <p>
3
- A multi API consuming weather forecasting superstar.
4
- </p>
5
- <p>
6
- Barometer provides a common public API to one or more weather services
7
- (APIs) of your choice. Weather services can co-exist to retrieve extensive
8
- information, or they can be used in a hierarchical configuration where
9
- lower preferred weather services are only used if previous services are
10
- unavailable.
11
- </p>
12
- <p>
13
- Barometer handles all conversions of the supplied query, so that the same
14
- query can be used for all (or most) services, even if they don&#8217;t
15
- support the query directly. See the &quot;Query&quot; section for more
16
- information on this.
17
- </p>
18
- <h2>version</h2>
19
- <p>
20
- Version 0.6.3 is the current release of this gem. The gem is available from
21
- github (attack-barometer) or rubyforge (barometer). It is fully functional
22
- (for five weather service APIs).
23
- </p>
24
- <h2>status</h2>
25
- <p>
26
- Currently this project is in development and will only work for a few
27
- weather services (wunderground, google, yahoo, weather.com, weather_bug).
28
- </p>
29
- <p>
30
- Features to be added next:
31
- </p>
32
- <ul>
33
- <li>even more weather service drivers (noaa)
34
-
35
- </li>
36
- <li>icon support
37
-
38
- </li>
39
- </ul>
40
- <h1>dependencies</h1>
41
- <h2>Google API key</h2>
42
- <p>
43
- In most cases you will need to have a free google geocode api key. Get one
44
- here: <a href="http://code.google.com/apis/maps/signup.html">code.google.com/apis/maps/signup.html</a>
45
- Then put it in the file &#8217;~/.barometer&#8217; by adding the lines:
46
- </p>
47
- <pre>
48
- google:
49
- geocode: YOUR_KEY_HERE
50
- </pre>
51
- <p>
52
- You will need this for:
53
- </p>
54
- <ul>
55
- <li>using the Barometer gem (unless you use queries that are directly supported
56
- by the weather source API, ie yahoo will take a zip code directly and
57
- doesn&#8217;t require any geocoding)
58
-
59
- </li>
60
- <li>running the Barometer binary
61
-
62
- </li>
63
- <li>running the Barometer Web Demo
64
-
65
- </li>
66
- </ul>
67
- <h3>other keys</h3>
68
- <p>
69
- The same file can hold all your weather service API keys.
70
- </p>
71
- <p>
72
- eg. weather.com
73
- </p>
74
- <pre>
75
- weather:
76
- partner: YOUR_PARTNER_KEY
77
- license: YOUR_LICENSE_KEY
78
- </pre>
79
- <p>
80
- eg. weatherbug.com
81
- </p>
82
- <pre>
83
- weather_bug:
84
- code: YOUR_API_CODE
85
- </pre>
86
- <h2>HTTParty</h2>
87
- <p>
88
- Why? HTTParty was created and designed specifically for consuming web
89
- services. I choose to use this over using the Net::HTTP library directly to
90
- allow for faster development of this project.
91
- </p>
92
- <p>
93
- HTTParty is also extended to include configurable Timeout support.
94
- </p>
95
- <h2>tzinfo</h2>
96
- <p>
97
- Why? Barometer deals with time information for locations all over the
98
- world. This information doesn&#8217;t mean that much if it can&#8217;t be
99
- converted to times that don&#8217;t correspond to the applicable timezone.
100
- Tzinfo handles this time zone manipulation.
101
- </p>
102
- <h1>queries</h1>
103
- <p>
104
- The query handling is one of the most beneficial and powerful features of
105
- Barometer. Every weather service accepts a different set of possible
106
- queries, so it usually the case that the same query can only be used for a
107
- couple weather services.
108
- </p>
109
- <p>
110
- Barometer will allow the use of all query formats for all services
111
- (mostly). It does this by first determining the original query format, then
112
- converting the query to a compatible format for each specific weather
113
- service.
114
- </p>
115
- <p>
116
- For example, Yahoo! only accepts US Zip Code or Weather.com ID. With
117
- Barometer you can query Yahoo! with a simple location (ie: Paris) or even
118
- an Airport code (ICAO) and it will return the weather as expected.
119
- </p>
120
- <h2>acceptable formats</h2>
121
- <ul>
122
- <li>zipcode
123
-
124
- </li>
125
- <li>icao (international airport code)
126
-
127
- </li>
128
- <li>coordinates (latitude and longitude)
129
-
130
- </li>
131
- <li>postal code
132
-
133
- </li>
134
- <li>weather.com ID
135
-
136
- </li>
137
- <li>location name (ie address, city, state, landmark, etc.)
138
-
139
- </li>
140
- <li>if the query is of the formats zipcode or postal code it may not support
141
- conversion to other formats.
142
-
143
- </li>
144
- </ul>
145
- <h2>conversion caching</h2>
146
- <p>
147
- Barometer has internal conversion caching. No conversion will be repeated
148
- during a measurement, thus limiting the number of web queries needed.
149
- </p>
150
- <p>
151
- Example: If you configure Barometer to use both Yahoo and Weather.com, then
152
- use a query like &quot;denver&quot;, this will require a conversion from
153
- &quot;denver&quot; to its weather.com weather_id. This conversion is needed
154
- for both web services but will only happen once and be cached.
155
- </p>
156
- <h1>usage</h1>
157
- <p>
158
- You can use barometer right out of the box, as it is configured to use one
159
- register-less (no API key required) international weather service
160
- (wunderground.com).
161
- </p>
162
- <p>
163
- For better results, signup for a google-map key and enhance your barometer
164
- with geo-coding.
165
- </p>
166
- <pre>
167
- require 'barometer'
168
-
169
- Barometer.google_geocode_key = &quot;THE_GOOGLE_API_KEY&quot;
170
- barometer = Barometer.new(&quot;Paris&quot;)
171
- weather = barometer.measure
172
-
173
- puts weather.current.temperture
174
- </pre>
175
- <h2>sources</h2>
176
- <p>
177
- The available sources are:
178
- </p>
179
- <pre>
180
- Wunderground.com (:wunderground) [default]
181
- Yahoo! Weather (:yahoo)
182
- Google Weather (:google)
183
- Weather.com (:weather_dot_com)
184
- WeatherBug.com (:weather_bug)
185
- </pre>
186
- <h2>source configuration</h2>
187
- <p>
188
- Barometer can be configured to use multiple weather service APIs (either in
189
- a primary/failover config or in parallel). Each weather service can also
190
- have its own config.
191
- </p>
192
- <p>
193
- Weather services in parallel
194
- </p>
195
- <pre>
196
- Barometer.config = { 1 =&gt; [:yahoo, :google] }
197
- </pre>
198
- <p>
199
- Weather services in primary/failover
200
- </p>
201
- <pre>
202
- Barometer.config = { 1 =&gt; [:yahoo], 2 =&gt; :wunderground }
203
- </pre>
204
- <p>
205
- Weather services, one with some configuration. In this case we are setting
206
- a weight value, this weight is respected when calculating averages.
207
- </p>
208
- <pre>
209
- Barometer.config = { 1 =&gt; [{:wunderground =&gt; {:weight =&gt; 2}}, :google] }
210
- </pre>
211
- <p>
212
- Weather services, one with keys.
213
- </p>
214
- <pre>
215
- Barometer.config = { 1 =&gt; [:yahoo, {:weather_dot_com =&gt; {:keys =&gt; {:partner =&gt; PARTNER_KEY, :license =&gt; LICENSE_KEY } }}] }
216
- </pre>
217
- <h3>multiple weather API, with hierarchy</h3>
218
- <pre>
219
- require 'barometer'
220
-
221
- Barometer.google_geocode_key = &quot;THE_GOOGLE_API_KEY&quot;
222
- # use yahoo and google, if they both fail, use wunderground
223
- Barometer.config = { 1 =&gt; [:yahoo, :google], 2 =&gt; :wunderground }
224
-
225
- barometer = Barometer.new(&quot;Paris&quot;)
226
- weather = barometer.measure
227
-
228
- puts weather.current.temperture
229
- </pre>
230
- <h2>command line</h2>
231
- <p>
232
- You can use barometer from the command line.
233
- </p>
234
- <pre>
235
- # barometer berlin
236
- </pre>
237
- <p>
238
- This will output the weather information for the given query. See the help
239
- for more command line information.
240
- </p>
241
- <pre>
242
- # barometer -h
243
- </pre>
244
- <h3>web demo</h3>
245
- <p>
246
- There is a Sinatra application that demos the functionality of Barometer,
247
- and provides Barometer information. Start this local demo with:
248
- </p>
249
- <pre>
250
- # barometer -w
251
- </pre>
252
- <p>
253
- NOTE: This requires the gems &quot;sinatra&quot; and &quot;vegas&quot;.
254
- </p>
255
- <h3>fail</h3>
256
- <p>
257
- What would cause a weather service to fail? The most obvious is that the
258
- particular weather service in currently unavailable or not reachable. Other
259
- possible reasons would include not having the API (or a valid API key for
260
- the particular weather service, if required), not providing a valid query,
261
- or providing a query for a location not supported by the weather service.
262
- </p>
263
- <p>
264
- For example, if you look at the example above, the query of
265
- &quot;Paris&quot; refers to a city in France. Yahoo weather services only
266
- supports weather results for USA (at least at the time of writing).
267
- Therefore, Barometer would not use Yahoo, just Google and failover to use
268
- Wunderground (if needed).
269
- </p>
270
- <h2>searching</h2>
271
- <p>
272
- After you have measured the data, Barometer provides several methods to
273
- help you get the data you are after. All examples assume you already have
274
- measured the data as shown in the above examples.
275
- </p>
276
- <h3>by preference (default service)</h3>
277
- <pre>
278
- weather.default # returns measurement for default source
279
- weather.current # returns current_measurement for default
280
- weather.now # returns current_measurement for default
281
- weather.forecast # returns all forecast_measurements for default
282
- weather.today # returns forecast_measurement for default today
283
- weather.tomorrow # returns forecast_measurement for default tomorrow
284
-
285
- puts weather.now.temperature.c
286
- puts weather.tomorrow.high.c
287
- </pre>
288
- <h3>by source</h3>
289
- <pre>
290
- weather.source(:wunderground) # returns measurement for specified source
291
- weather.sources # lists all successful sources
292
-
293
- puts weather.source(:wunderground).current.temperature.c
294
- </pre>
295
- <h3>by date</h3>
296
- <pre>
297
- # note, the date is the date of the locations weather, not the date of the
298
- # user measuring the weather
299
- date = Date.parse(&quot;01-01-2009&quot;)
300
- weather.for(date) # returns forecast_measurement for default on date
301
- weather.source(:wunderground).for(date) # same as above but specific source
302
-
303
- puts weather.source(:wunderground).for(date).high.c
304
- </pre>
305
- <h3>by time</h3>
306
- <pre>
307
- # note, the time is the time of the locations weather, not the time of the
308
- # user measuring the weather
309
- time = Time.parse(&quot;13:00 01-01-2009&quot;)
310
- weather.for(time) # returns forecast_measurement for default at time
311
- weather.source(:wunderground).for(time) # same as above but specific source
312
-
313
- puts weather.source(:wunderground).for(time).low.f
314
- </pre>
315
- <h2>averages</h2>
316
- <p>
317
- If you consume more then one weather service, Barometer can provide
318
- averages for the values (currently only for the &#8216;current&#8217;
319
- values and not the forecasted values).
320
- </p>
321
- <pre>
322
- require 'barometer'
323
-
324
- Barometer.google_geocode_key = &quot;THE_GOOGLE_API_KEY&quot;
325
- # use yahoo and wunderground
326
- Barometer.config = { 1 =&gt; [:yahoo, :wunderground] }
327
-
328
- barometer = Barometer.new(&quot;90210&quot;)
329
- weather = barometer.measure
330
-
331
- puts weather.temperture
332
- </pre>
333
- <p>
334
- This will calculate the average temperature as given by :yahoo and
335
- :wunderground
336
- </p>
337
- <h3>weights</h3>
338
- <p>
339
- You can weight the values from a weather service so that the values from
340
- that web service have more influence then other values. The weights are set
341
- in the config &#8230; see the config section
342
- </p>
343
- <h2>simple answers</h2>
344
- <p>
345
- After you have measured the data, Barometer provides several &quot;simple
346
- answer&quot; methods to help you get answers to some basic questions. All
347
- examples assume you already have measured the data as shown in the above
348
- examples.
349
- </p>
350
- <p>
351
- All of these questions are ultimately specific to the weather source(s) you
352
- are configured to use. All sources that have successfully measured data
353
- will be asked, but if there is no data that can answer the question then
354
- there will be no answer.
355
- </p>
356
- <h3>is it windy?</h3>
357
- <pre>
358
- # 1st parameter is the threshold wind speed for being windy
359
- # 2nd parameter is the utc_time for which you want to know the answer,
360
- # this defaults to the current time
361
- # NOTE: in my example the values are metric, so the threshold is 10 kph
362
-
363
- weather.windy?(10)
364
- </pre>
365
- <h3>is it wet?</h3>
366
- <pre>
367
- # 1st parameter is the threshold pop (%) for being wet
368
- # 2nd parameter is the utc_time for which you want to know the answer,
369
- # this defaults to the current time
370
- # NOTE: in my example the threshold is 50 %
371
-
372
- weather.wet?(50)
373
- </pre>
374
- <h3>is it sunny?</h3>
375
- <pre>
376
- # 1st parameter is the utc_time for which you want to know the answer,
377
- # this defaults to the current time
378
-
379
- weather.sunny?
380
- </pre>
381
- <h3>is it day?</h3>
382
- <pre>
383
- # 1st parameter is the utc_time for which you want to know the answer,
384
- # this defaults to the current time
385
-
386
- weather.day?
387
- </pre>
388
- <h3>is it night?</h3>
389
- <pre>
390
- # 1st parameter is the utc_time for which you want to know the answer,
391
- # this defaults to the current time
392
-
393
- weather.night?
394
- </pre>
395
- <h1>design</h1>
396
- <ul>
397
- <li>create a Barometer instance
398
-
399
- </li>
400
- <li>supply a query, there are very little restrictions on the format:
401
-
402
- <ul>
403
- <li>city, country, specific address (basically anything Google will geocode)
404
-
405
- </li>
406
- <li>US zip code (skips conversion if weather service accepts this directly)
407
-
408
- </li>
409
- <li>postal code (skips conversion if weather service accepts this directly)
410
-
411
- </li>
412
- <li>latitude and longitude (skips conversion if weather service accepts this
413
- directly)
414
-
415
- </li>
416
- <li>weather.com weather id (even if the service you are using doesn&#8217;t use
417
- it)
418
-
419
- </li>
420
- <li>international airport code (skips conversion if weather service accepts
421
- this directly)
422
-
423
- </li>
424
- </ul>
425
- </li>
426
- <li>determine which weather services will be queried (one or multiple)
427
-
428
- </li>
429
- <li>if query conversion required for specific weather service, convert the
430
- query
431
-
432
- </li>
433
- <li>query the weather services
434
-
435
- </li>
436
- <li>save the data
437
-
438
- </li>
439
- <li>repeat weather service queries as needed
440
-
441
- </li>
442
- </ul>
443
- <h1>extending</h1>
444
- <p>
445
- Barometer attempts to be a common API to any weather service API. I have
446
- included several weather service &#8216;drivers&#8217;, but I know there
447
- are many more available. Please use the provided ones as examples to create
448
- more.
449
- </p>
450
- <h2>copyright</h2>
451
- <p>
452
- Copyright &#169; 2009 Mark G. See LICENSE for details.
453
- </p>