NAME

Weather::Google - Perl interface to Google's Weather API

VERSION

Version 0.06

DEPRECATION

This module is now deprecated.

Some time in August 2012, Google unexpectedly pulled the plug on the iGoogle Weather API (it was allegedly "undocumented" at the time, though there was at least documentation when this module was written originally in 2008). Since there is appears to be no intention of reviving the service, this module is being deprecated.

While there are unfortunately no drop-in replacements (this module heavily leveraged the simplicity and flexibility of Google's API), please consider using one of the many other weather modules, on CPAN, such as Weather::Underground - most of the other weather modules are more powerful than Google::Weather ever was.

The module will no longer work, instead giving deprecation warnings when called. The documentation remains for historical purposes.

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'});

 # Encoding is optional, should be handled properly without specifying
 $gw = new Weather::Google(
    'Paris, France',
    {language => 'fr', encoding => 'latin1'},
 );

 # Or
 $gw = new Weather::Google;
 $gw->zip(90210); # Zip code
 $gw->city('Beverly Hills, CA'); # City name
 $gw->language('de'); # Localization

 $gw->language('fr');

 # Again, this is optional.
 $gw->encoding('latin1');

 ## 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.

encoding

Optionally takes a character encoding as an argument (i.e. "latin1", "utf-8") to set the encoding that is expected from the server for proper localization. (Default: language specific, or "utf-8")

Returns the currently set encoding, or the language default.

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

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.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Weather::Google

You can also look for information at:

ACKNOWLEDGEMENTS

Some of the localization code provided by Alex Linke.

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