NAME

Weather::Underground - Perl extension for retrieving weather information from wunderground.com

SYNOPSIS

use Weather::Underground;

$weather = Weather::Underground->new(
	place => "Montreal, Canada",
	debug => 0,
	)
	|| die "Error, could not create new weather object: $@\n";

$arrayref = $weather->get_weather()
	|| die "Error, calling get_weather() failed: $@\n";

foreach (@$arrayref) {
	print "MATCH:\n";
	while (($key, $value) = each %{$_}) {
		print "\t$key = $value\n";
	}
}

DESCRIPTION

Weather::Underground is a perl module which provides a simple OO interface to retrieving weather data for a geographic location. It does so by querying wunderground.com and parsing the returned results.

CONSTRUCTOR

new(hash or hashref);

Creates and returns a new Weather::Underground object.

Takes either a hash (as the SYNOPSIS shows) or a hashref

Required keys in the hash:

place

This key should be assigned the value of the geographical place you would like to retrieve the weather information for. The format of specifying the place really depends on wunderground.com more than it depends on this perl module, however at the time of this writing they accept 'City', 'City, State', 'State', 'State, Country' and 'Country'.

Optional keys in the hash:

cache_file

This key should be assigned a file name to use as a cache. The module will store and use data from that file instead of querying wunderground.com if cache_max_age has not been exceeded.

This key is ignored if the cache_max_age key is not supplied.

cache_max_age

This key should be assigned a numeric value which is the number of seconds after which any data in the cache_file will be considered too old and a new request will be made to wunderground.com

This key is ignored if the cache_file key is not supplied.

debug

This key should be set to a true or false false. A false value means no debugging information will be printed, a true value means debug information will be printed.

METHODS

get_weather()

This method is used to initiate the connection to wunderground.com, query their system, and parse the results or retrieve the results from the cache_file constructor key if appropriate.

If no results are found, returns undef.

If results are found, returns an array reference. Each element in the array is a hash reference. Each hash contains information about a place that matched the query;

Each hash contains the following keys:

place

(the exact place that was matched)

temperature_celsius

(the temperature in celsius)

temperature_fahrenheit

(the temperature in fahrenheit)

humidity

(humidity percentage)

conditions

(current sky, example: 'Partly cloudy')

wind

(wind direction and speed)

pressure

(the barometric pressure)

windchill_celsius

(the temperature in celsius with wind chill considered)

windchill_fahrenheit

(the temperature in fahrenheit with wind chill considered)

updated

(when the content was last updated on the server)

NOTICE

1. Your query may result in more than 1 match. Each match is a hash reference added as a new value in the array which get_weather() returns the reference to.

2. Due to the differences between single and multiple-location matches, some of the keys listed above may not be available in multi-location matches.

EXAMPLES

Example 1: Print all matching information

See SYNOPSIS

Example 2: Print the Celsius temperature of the first matching place

use Weather::Underground;

$weather = Weather::Underground->new(
	place   =>      "Montreal",
	debug           =>      0
	)
	|| die "Error, could not create new weather object: $@\n";

$arrayref = $weather->get_weather()
	|| die "Error, calling get_weather() failed: $@\n";

print "The celsius temperature at $arrayref->[0]->{place} is $arrayref->[0]->{temperature_celsius}\n";

ERRORS

All methods return something that evaluates to true when successful, or undef when not successful.

If the constructor or a method returns undef, the variable $@ will contain a text string containing the error that occurred.

AUTHOR

Mina Naguib http://www.topfx.com mnaguib@cpan.org

COPYRIGHT

Copyright (C) 2002-2003 Mina Naguib. All rights reserved. Use is subject to the Perl license.