Weather(3)

NAME
Geo::Weather - Weather retrieval module

SYNOPSIS
  use Geo::Weather;

  my $weather = new Geo::Weather;

  $weather->get_weather('Folsom','CA');

  print $weather->report();

  -or-

  use Geo::Weather;

  my $weather = new Geo::Weather;
  $weather->{timeout} = 5; # set timeout to 5 seconds instead of the default of 10

  my $current = $weather->get_weather('95630');

  print "The current temperature is $current->{temp} degrees\n";

DESCRIPTION
The Geo::Weather module retrieves the current weather from weather.com when given city and state or a US zip code. Geo::Weather relies on LWP::UserAgent to work. In order for the timeout code to work correctly, you must be using a recent version of libwww-perl and IO::Socket. Geo::Weather was developed with libwww-perl 5.53 and IO::Socket 1.26.

FUNCTIONS

•   new

    Create and return a new object.

•   get_weather

    Gets the current weather from weather.com

    Arguments

            city - US city or zip code
            state - US state, not needed if using zip code

    Sample Code

            my $current = $weather->get_weather('Folsom','CA');
            if (!ref $current) {
                    die "Unable to get weather information\n";
            }

    Returns

            On sucess, get_weather returns a hashref  containing the following keys

            city            - City
            state           - State
            zip             - Zipcode of US city
            pic             - weather.com URL to the current weather image
            url             - Weather.com URL to the weather results
            cond            - Current condition
            temp            - Current temperature (degees F)
            wind            - Current wind speed
            dewp            - Current dew point (degrees F)
            humi            - Current rel. humidity
            visb            - Current visibility
            baro            - Current barometric pressure
            heat            - Current heat index (Feels Like string)

            On error, it returns the following exported error variables

    Errors

            $ERROR_QUERY            - Invalid data supplied
            $ERROR_PAGE_INVALID     - No URL, or incorrectly formatted URL for retrieving the information
            $ERROR_CONNECT          - Error connecting to weather.com
            $ERROR_NOT_FOUND        - Weather for the specified city/state or zip could not be found
            $ERROR_TIMEOUT          - Timed out while trying to connect or get data from weather.com

•   report

    Returns an HTML table containing the current weather. Must call get_weather first.

    Sample Code

            print $weather->report();

•   report_raw

    Returns pipe delimited string containing the current weather. Must call get_weather first.

     Fields are: city|state|pic|cond|temp|wind|dewp|humi|visb|baro|uv

    Sample Code

            my $current = $weather->report_raw();

•   report_forecast

    Returns an HTML table containing the ten day forecast. Must call get_weather first.

    Arguments

            table_width - Optional (integer) table width for the report. Default is '80'.

    Sample Code

            my $forecast = $weather->report_forecast();

•   set_report_colors

    Set the HTML color values for the weather report. Must call before report or report_forecast to be effective. (DUH!)

    Arguments

            report_hdr_color - Report header color. Default is '#000000'.
            report_cond_color - Report conditions color. Default is '#000080'.
            report_result_color - Report reults color. Default is '#0000a0'.

    Sample Code

            my $status = $weather->set_report_colors('#ff0000', '#00ff00', '#0000ff');

    Returns

            0 if passed a bad value.
            1 if successful.

•   data_check

    Returns a boolean value indicating if valid weather data appears to have been retrieved. Must call get_weather first.

    Sample Code

            my $valid = $weather->data_check();
            unless ($valid) {
                    die "The weather data retrieved appears to be bad or missing.\n";
            }

•   get_city

    Returns string containing the current weather city. This is useful when looking up weather by zip code. Must call get_weather first.

    Sample Code

            my $city = $weather->get_city();

•   get_state

    Returns string containing the current weather state. This is useful when looking up weather by zip code. Must call get_weather first.

    Sample Code

            my $state = $weather->get_state();

•   lookup

    Gets current weather given a full weather.com URL

    Sample Code

            my $current = $weather->lookup('http://www.weather.com/search/search?where=95630');

    Returns

            On sucess, lookup returns a hashref with the same keys as the get_weather function.

            On error, lookup returns the same errors defined for get_weather.

•   lookup_forecast

    Gets the ten day forecast page given a full weather.com URL. Not intended to be called directly, but used by report_forecast.

    Sample Code

            my $raw_forecast = $weather->lookup_forecast('http://www.w3.weather.com/weather/print/95630');

    Returns

            On sucess, lookup_forecast returns an array containing the weather.com ten day forecast page data.

            On error, lookup_forecast returns the same errors defined for get_weather.

OBJECT KEYS
There are several object hash keys that can be set to manipulate how Geo::Weather works. The hash keys should be set directly following "new".

Below is a list of each key and what it does:

•   debug

    Enable debug output of the connection attempts to weather.com Valid values are 0 to 4, increasing debugging respectivley.

•   timeout

    Controls the timeout, in seconds, when trying to connect to or get data from weather.com. Default timeout is 10 seconds. Set to 0 to disable timeouts.

•   proxy

    Use HTTP proxy for the request. Format is http://proxy.server:port/. Default is no proxy.

•   proxy_user

    Sets the username to use for proxying. Defaults to the HTTP_PROXY_USER environment variable, if set, or don't use authentication if blank.

•   proxy_pass

    Sets the password to use for proxying. Defaults to the HTTP_PROXY_PASS environment variable, if set.

•   *agent_string

    HTTP User-Agent header for request. Default is Geo::Weather/$VERSION.

AUTHOR
 Geo::Weather was wrtten by Mike Machado I<E<lt>mike@innercite.comE<gt>>

POD ERRORS
Hey! The above document had some coding errors, which are explained below:

Around line 888:
    '=item' outside of any '=over'

Around line 909:
    Expected '=item *'

Around line 913:
    You forgot a '=back' before '=head1'