/ 
WWW-Wunderground-API-0.08
River stage zero No dependents
/ WWW::Wunderground::API

NAME

WWW::Wunderground::API - Use Weather Underground's JSON/XML API

VERSION

Version 0.08

SYNOPSIS

Connects to the Weather Underground JSON/XML service and parses the response data into something usable.

The entire response is available in Hash::AsObject form, so any data that comes from the server is accessible. Print a dump of "data()" to see all of the tasty data bits available.

use WWW::Wunderground::API;

# location
my $wun = new WWW::Wunderground::API('Fairfax, VA');

# or zipcode
my $wun = new WWW::Wunderground::API('22030');

# or airport identifier
my $wun = new WWW::Wunderground::API('KIAD');

# exercise several options

my $wun = new WWW::Wunderground::API(
  location => '22152',
  api_key => 'my wunderground api key',
  auto_api => 1,
  lang => 'FR',
  cache => Cache::FileCache->new({ namespace=>'wundercache', default_expires_in=>2400 }) #A cache is probably a good idea.
);


# Check the wunderground docs for details, but here are just a few examples

# the following $t1-$t6 are all equivalent:
$wun->location(22152);

$t1 = $wun->api_call('conditions')->temp_f
$t2 = $wun->api_call('conditions', 22152)->temp_f
$t3 = $wun->api_call('conditions', {location=>22152})->temp_f
$t4 = $wun->api_call('conditions', location=>22152)->temp_f
$t5 = $wun->conditions->temp_f
$t6 = $wun->temp_f

# simple current conditions
print 'The temperature is: '.$wun->conditions->temp_f."\n";
print 'The rest of the world calls that: '.$wun->conditions->temp_c."\n";

# radar/satellite imagery
my $sat_gif = $wun->satellite; #image calls default to 300x300 gif
my $rad_png = $wun->radar( format=>'png', width=>500, height=>500 ); #or pass parameters to be specific
my $rad_animation = $wun->animatedsatellite(); #animations are always gif

# almanac / forecast / more.
print 'Record high temperature year: '.$wun->almanac->temp_high->recordyear."\n";
print "Sunrise at:".$wun->astronomy->sunrise->hour.':'.$wun->astronomy->sunrise->minute."\n";
print "Simple forecast:".$wun->forecast->simpleforecast->forecastday->[0]{conditions}."\n";
print "Text forecast:".$wun->forecast->txt_forecast->forecastday->[0]{fcttext}."\n";
print "Long range forecast:".$wun->forecast10day->txt_forecast->forecastday->[9]{fcttext}."\n";
print "Chance of rain three hours from now:".$wun->hourly->[3]{pop}."%\n";
print "Nearest airport:".$wun->geolookup->nearby_weather_stations->airport->{station}[0]{icao}."\n";

# Conditions is autoloaded into the root of the object
print "Temp_f:".$wun->temp_f."\n";

METHODS/ACCESSORS

update()

Included for backward compatibility only. Refetches conditions data from the server. It will be removed in a future release. If you specify an api_key then this is equivalent of ->api_call('conditions') and is subject to the same cache

location()

Set the location. For example:

my $wun = new WWW::Wunderground::API('22030');
my $ffx_temp = $wun->conditions->temp_f;

$wun->location('KJFK');
my $ny_temp = $wun->conditions->temp_f;

$wun->location('San Diego, CA');
my $socal_temp = $wun->conditions->temp_f;

Valid locations can be derived from others by calling the geolookup endpoint, but you probably already know where you are.

auto_api

set auto_api to something truthy to have the module automatically make API calls without the use of api_call()

api_call( api_name, <location> )

Set api_name to any location-based wunderground api call (almanac,conditions,forecast,history...).

Location is optional and defaults to "location()". Can be any valid location (eg 22152,'KIAD','q/CA/SanFrancisco',...)

#Almanac data for 90210
$wun->api_call('almanac','90210');

#If auto_api=>1 the following is equivalent
$wun->location(90120);
$wun->almanac;

#10 day forecast for New York
$wun->api_call('forecast10day'','KJFK');

lang()

Set/Get current language for the next API call. The default language is 'EN'. See the wunderground API doc for a list of available languages.

raw()

Returns raw text result from the most recent API call. This will be either xml or json depending on api_type. You can also set this to whatever json/xml you'd like, though I can't imagine why you'd want to.

cache()

Specify a cache object. Needs only to satisfy get(key) and set(key,value) interface. Any Cache::Cache or CHI cache should work.

xml()

*Deprecated* - use "raw()" instead.

Returns raw xml result from wunderground server where applicable

json()

*Deprecated* - use "raw()" instead.

Returns raw json result from wunderground server where applicable

data()

Contains all weather data from server parsed into convenient Hash::AsObject form;

api_key()

Required for JSON api access. Defaults to $ENV{WUNDERGROUND_API}

api_type()

Defaults to json. If no api_key is specified it will be set to xml and only basic weather conditions will be available.

AUTHOR

John Lifsey, <nebulous at crashed.net>

BUGS

Please report any bugs or feature requests to bug-www-wunderground-api at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=WWW-Wunderground-API. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SOURCE

Better yet, fork on github and send me a pull request: https://github.com/nebulous/WWW-Wunderground-API

SUPPORT

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

perldoc WWW::Wunderground::API

You can also look for information at:

SEEALSO

If you'd like to scrape from Weather Underground rather than have to use the API, see Weather::Underground. WWW::Wunderground::API only supports current conditions without an API key.

LICENSE AND COPYRIGHT

Copyright 2013 John Lifsey.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.