/
README
270 lines (205 loc) · 9.48 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
NAME
Weather::Google - Perl interface to Google's Weather API
VERSION
Version 0.04
SYNOPSIS
use Weather::Google;
# If you plan on using locations with non-ASCII characters
use encoding 'utf8';
my $gw;
## Initialize the module
$gw = new Weather::Google(90210); # Zip code
$gw = new Weather::Google('Beverly Hills, CA'); # City name
$gw = new Weather::Google('Herne, Germany',{language => 'de'});
# Or
$gw = new Weather::Google;
$gw->zip(90210); # Zip code
$gw->city('Beverly Hills, CA'); # City name
$gw->language('de'); # Localization
## Get some current information
my @info;
@info = $gw->current('temp_f','temp_c','humidity','wind_condition');
# Or
my $current = $gw->current;
@info = ($current->{temp_f}, $current->{temp_c}, $current->{humidity});
# Or
@info = ($gw->temp_f, $gw->temp_c, $gw->humidity, $gw->wind_condition);
## Forecast
print "Today's high: ", $gw->forecast(0,'high');
print "Today's high: ", $gw->forecast('Today','high');
print "Today's high: ", $gw->today('high');
# Assuming Today is Monday:
print "Tomorrow's high: ", $gw->forecast(1,'high');
print "Tomorrow's high: ", $gw->forecast('Tue','high');
print "Tomorrow's high: ", $gw->tue('high');
## Forecast information:
print "Forecast for ". $gw->info('city'). "made at ".
$gw->info('current_date_time');
DESCRIPTION
Weather::Google provides a simple interface to Google's Weather API.
METHODS
new Initializes and returns a Weather::Google object. Optionally takes a
Zip/postal code or city name as an argument, optionally followed by
a hashref of additional options:
language
Have a look at the language() method's description below.
zip Sets the zip/postal code for the Weather::Google object. Takes a 5
digit integer as an argument. Returns 1 on success.
city
Sets the city for the Weather::Google object. Takes a string as an
argument. Returns 1 if successful.
language
Optionally takes an ISO language code as an argument (i.e. "en",
"de") to set the language that is passed to the weather query for
proper localization. (Default: "en")
Supported language codes: "en", "da", "de", "es", "fi", "fr", "it",
"ja", "ko", "nl", "no", "pt-BR", "ru", "sv", "zh-CN", "zh-TW"
Returns the currently set ISO language code.
current_conditions
Method to report on current weather conditions. With no argument,
this returns a hash reference containing weather information.
Optionally takes an array of conditions to fetch.
Returns a scalar containing the requested information if only one
argument is passed, or an array of information if multiple arguments
are passed. The information will be in the same order as requested;
nonexistant information is returned as undef.
# Example 1:
my $info = $gw->current_conditions;
foreach my $condition ( keys ( %$info ) ) {
print "$condition: ", $info->{$condition}, "\n";
}
# Example 2:
my @info = $gw->current_conditions('temp_f','temp_c');
print "Temperature in F and C: @info";
# Example 3:
my $temp_f = $gw->current_conditions('temp_f');
my $temp_c = $gw->current_conditions('temp_c');
print "It is $temp_f F ($temp_c C) degrees\n";
ARGUMENTS
The current_conditions() method will take any string as an
argument, but will return undefs if the information is not
available. It is generally safe to use the following strings as
arguments:
icon
temp_f
temp_c
wind_condition
humidity
condition
See also the ALIASES section for easier methods to access
current_conditions().
forecast_conditions
Method to report on weather conditions over the next few days. With
no argument, this returns an array reference containing a hash
reference containing weather information for each day available.
Optionally takes a day of the week (as a string containing the first
three letters of the day) or an array index number (where 0 is
today, 1 is tomorrow, etc.) as the first argument, and an array of
conditions to fetch as subsequent arguments..
If a day is given, but no conditions are passed, this method will
return a hash reference containing conditions for that day.
If conditions are passed, this method returns a scalar containing
the requested information if only one condition is requested, or an
array of information if multiple conditions are requested. The
information will be in the same order as requested; nonexistant
information is returned as undef.
# Example 1:
my $days = $gw->forecast_conditions;
foreach my $day (@$days) {
# See Example 2
}
# Example 2:
my $today = $gw->forecast_conditions(0);
print "High: ".$today->{high}."\n";
# Example 3:
my $tom_high = $gw->forecast_conditions(1,'high');
my $tue_low = $gw->forecast_conditions('Tue','low);
print "Tomorrow's high is $tom_high and Tuesday's low is $tue_low\n";
ARGUMENTS
The forecast_conditions() method will take any string as an
argument, but will return undefs if the information is not
available.It is generally safe to use the following strings as
arguments:
icon
high
low
day_of_week
condition
See also the ALIASES section for easier methods to access
forecast_conditions().
forecast_information
Method to report various information about the forecast itself. With
no argument, this returns a hash reference containing various
information. Optionally takes an array of conditions to fetch.
Returns a scalar containing the requested information if only one
argument is passed, or an array of information if multiple arguments
are passed. The information will be in the same order as requested;
nonexistant information is returned as undef.
# Example 1:
my $info = $gw->forecast_information;
print "Zip: ".$info->{postal_code}."\n";
# Example 2:
my $city = $gw->forecast_information('city');
print "Forecast for $city:\n";
# Example 3:
my @info = $gw->forecast_information('city','postal_code');
ARGUMENTS
The forecast_informatio() method will take any string as an
argument, but will return undefs if the information is not
available. It is generally safe to use the following strings as
arguments:
forecast_date
current_date_time
city
postal_code
unit_system
latitude_e6
longitude_e6
Using latitude_e6 or longitude_e6 may return undef or strange
values, since Google doesn't normally set them.
See also the ALIASES section for easier methods to access
forecast_information().
err This method returns the most recent error.
This is generally useful if you expect one of the other methods to
return something, but it returns undef instead.
ALIASES
Using the methods defined in METHODS in a script can get annoying very
quickly. Luckily, Weather::Google provides methods that can be used as
aliases for the defined methods.
SIMPLE ALIASES
The methods current(), forecast(), and info() can be used in place of
current_conditions(), forecast_conditions(), and forecast_information()
respectively.
DAY OF WEEK
The methods today(), tomorrow(), mon(), tue(), wed(), thu(), fri(),
sat(), and sun() can be used as alias to forecast_conditions($day),
where $day is the name of the method.
You can also use the full name (i.e., monday() or tuesday()) as opposed
to the first three letters.
CURRENT CONDITION
Any other method is used as an alias to current_conditions($method)
where $method is the name of the method. This means, for example, you
can use temp_f() as an implied alias for current_conditions('temp_f'),
and so on.
AUTHOR
Daniel LeWarne "<possum at cpan.org>"
BUGS
Google's XML files occasionally sends invalid UTF-8. Google::Weather can
generally compensate for this, bu if you would like to force
Google::Weather to strip utf8 characters instead of trying to re-encode
them, you can say
use Weather::Google;
$Weather::Google::ENCODE=0;
to force non-ASCII characters to be stripped from the output.
Please report any bugs or feature requests to "bug-weather-google at
rt.cpan.org", or through the web interface at
<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Weather-Google>. I will
be notified, and then you'll automatically be notified of progress on
your bug as I make changes.
COPYRIGHT
Copyright (C) 2008 Daniel "Possum" LeWarne. All Rights Reserved.
This program is free software, you can redistribute it and/or modify it
under the same terms as Perl itself.
SEE ALSO
This (very briefly) discusses the Weather API
<http://toolbar.google.com/buttons/apis/howto_guide.html>