/ 
Weather-Bug-0.25
River stage zero No dependents
/ Weather::Bug

NAME

Weather::Bug - Provide an object oriented interface to the WeatherBug API.

VERSION

This document describes Weather::Bug version 0.25

SYNOPSIS

  use Weather::Bug;

  my $wxbug = Weather::Bug->new( -key => 'YOURKEYHERE' );

DESCRIPTION

The Weather::Bug module provides an object-oriented wrapper around the WeatherBug web API. An object of this class performs requests and parses the output to provide an easier interface for retrieving weather information.

Use of this module requires registering with WeatherBug to acquire a license key. This key provides a developer with access to the API.

INTERFACE

The module supports several methods that access the WeatherBug API. In addition, the module supports a few convenience methods that simplify access to the underlying functionality by other classes.

The object is created using the new class method. It takes a single required named parameter -key, whose value is the license key you obtained from WeatherBug.

The constructor also supports an optional parameter -getsub whose value is a coderef that works as a standin for LWP::Simple::get. This is useful for testing, or if you need to get your data from somewhere other than an HTTP request.

WeatherBug API Methods

These methods provide high-level access to the WeatherBug API.

list_stations

This method takes one parameter, a US zipcode giving a start location to look for WeatherBug stations. The method returns a list of Weather::Bug::Station objects representing the stations near the requested location. The definition of near and the number of stations returned depends on the density of stations in the area of interest.

On failure, the method returns an empty list.

get_forecast

Retrieve the 7-day forecast for the supplied zipcode as a Weather::Bug::SevenDayForecast object.

On failure, the method returns undef.

get_alerts

This method takes one parameter, a US zipcode giving a location to check for alerts. The method returns a list of Weather::Bug::Alert objects representing alerts that apply at the current time.

If there are no alerts, the method returns an empty list.

get_live_compact_weather

This method requires two named parameters: zipcode and StationID. The method provides access to what WeatherBug refers to as Live Compact Weather as a Weather::Bug::CompactWeather object.

get_live_weather

This method requires two named parameters: zipcode and StationID. The method provides access to what WeatherBug refers to as Live Weather as a Weather::Bug::Weather object.

Convenience Methods

These utility methods are used by some of the other Weather::Bug classes to do their work. Some of these methods may be used for lower-level access to the WeatherBug API.

request

This method takes two parameters, a cmd name and a hash containing parameters to pass to the command.

The cmd parameter is the filename used in the URL for that API method, without the extension. Supported commands are:

getStations
getFullForecast
getLiveWeather
getLiveCompactWeather
getalerts

This allows an extension point in the class. If WeatherBug extends their API, this method can be used to make a call in the same way as any of the other methods.

Using this method, the URL is created mostly automatically including the hostname, the file extension, and the acode parameter supplying the license key.

On success, the method returns the body of the response as a string. On failure, the method dies.

DIAGNOSTICS

This section lists error messages that this module may display.

Request for '%s' failed.

The request to the WeatherBug API was not successful. The %s is the name of the page that failed.

Unable to parse output from '%s' request.

Although the WeatherBug API did return successfully, the output could not be parsed as well-formed XML. The %s is the name of the page that failed.

No '%s' node found.

Although the WeatherBug API did return successfully, the output XML did not contain the specified node.

CONFIGURATION AND ENVIRONMENT

Weather::Bug requires no configuration files or environment variables.

DEPENDENCIES

This module depends on Moose, LWP::Simple, and XML::LibXML.

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-weather-weatherbug@rt.cpan.org, or through the web interface at http://rt.cpan.org.

ACKNOWLEDGEMENTS

The following people have contributed to this module.

  • Joseph Hull

  • Gordon Child

AUTHOR

G. Wade Johnson <wade@anomaly.org>

LICENCE AND COPYRIGHT

Copyright (c) 2008, G. Wade Johnson <wade@anomaly.org>. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic.

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.