Weather::NOAA::Alert - Polling and parsing of NOAA CAP 1.1 Alerts
Version 0.90
my $alert = Weather::NOAA::Alert->new(['TXZ104', 'TXC082', 'TXZ097']); my $events = $alert->get_events(); my ($errorCount, $eventCount, $addCount, $deleteCount) = $alert->poll_events();
Weather::NOAA::Alert will retrieve and parse the NOAA National Weather Service ATOM and CAP 1.1 feeds for the specified forecast zones. It is designed to cache previously polled CAP items. The overall process is to get the requested ATOM feed, get any CAP entries that are not in the cache, and store the alerts.
You can find the zone list and more information about NOAA watches, warnings, and advisories at the following sites:
Zone List: http://alerts.weather.gov/
Zone Maps: http://www.weather.gov/mirs/public/prods/maps/pfzones_list.htm
use Weather::NOAA::Alert; use Data::Dumper; my $SLEEP_SECS = 60; #Poll every 1 minute #my $alert = Weather::NOAA::Alert->new(['US']); my $alert = Weather::NOAA::Alert->new(['TXC085', 'TXZ097']); $alert->printLog(1); $alert->errorLog(1); my $events = $alert->get_events(); while (1) { my ($errorCount, $eventCount, $addCount, $deleteCount) = $alert->poll_events(); print Dumper( $events) . "\n"; print "Tracking $eventCount " . ($eventCount ==1 ? "event" : "events"); print " $addCount added, $deleteCount deleted"; print ", $errorCount " . ($errorCount ==1 ? "error" : "errors"); print "\n"; print "Sleeping $SLEEP_SECS seconds\n-----------------\n\n"; sleep($SLEEP_SECS); }
$alert = Weather::NOAA:Alert->new(@zones); $alert = Weather::NOAA:Alert->new();
An array reference may be provided with the list of NOAA forecast zones that should be polled. If the list is not supplied then you must call $object->zones(@zones) to set the zone list prior to calling $object->poll_events().
$object->zones(@zones)
$object->poll_events()
$object->zones([zone1, zone2, ...]); @zones = $object->zones();
Setting the zone list will overwrite the existing list with the supplied list. If called with no arguments, returns a reference to the current zone array. To return data for all zones use "US".
%events = $object->get_events();
This is the primary output of the Weather::NOAA::Alert module. The data structure is the result of parsing the NOAA CAP 1.1 objects retrieved for the specified zones. The events hash is indexed first by zone, then by the CAP ID.
Remembers past events in a data structure hash consisting of: {zone}->{CAP id}->{'delete'} ->{'actionTime'} ->{'event'} ->{'certainty'} ->{'senderName'} ->{'urgency'} ->{'instruction'} ->{'description'} ->{'category'} ->{'severity'} ->{'effective'} ->{'headline'} ->{'expires'}
{zone}->{CAP id}->{'delete'}
->{'actionTime'}
->{'event'}
->{'certainty'}
->{'senderName'}
->{'urgency'}
->{'instruction'}
->{'description'}
->{'category'}
->{'severity'}
->{'effective'}
->{'headline'}
->{'expires'}
Note that the hash keys are dynamically created from the <info> section of the event. If NOAA adds, renames, or removes an XML parameter it will also change in the structure. In addition, nothing is currently parsed from the event header. There are XML parameters in the header that might be interesting to collect but I didn't have a use for any of that data. Future module revisions might include more of the NOAA data.
$object->formatTime( [1 | 0] ); $curr_setting = $object->formatTime();
When called without parameters will return the current setting.
$object->formatAsterisk( [1 | 0] ); $curr_setting = $object->formatAsterisk();
$object->printLog( [1 | 0] ); $curr_setting = $object->printLog();
$object->printActions( [1 | 0] ); $curr_setting = $object->printActions();
$object->errorLog( [1 | 0] ); $curr_setting = $object->errorLog();
$object->diagDump( [1 | 0] ); $curr_setting = $object->diagDump();
Dumps all atom files received to the file diagnostics.txt in the current directory. When called without parameters will return the current setting.
$object->atomURLZone( $url ); $curr_setting = $object->atomURLZone();
When called without parameters will return the current setting. The default setting is:
http://alerts.weather.gov/cap/wwaatmget.php?x=
$object->atomURLUS( $url ); $curr_setting = $object->atomURLUS();
http://alerts.weather.gov/cap/us.atom
my $version = Weather::NOAA::Alert->VERSION;
my ($errorCount, $eventCount, $addCount, $deleteCount) = $object->poll_events();
Polls the National Weather Service Public Alerts and updates the events hash for each event. Returns an array of counts:
$errorCount - The number of errors encountered while pulling the Atom files
$eventCount - The number of actively tracked events
$addCount - The number of events added on this poll
$deleteCount - The number of events deleted on this poll
The following items represent fragile parts of the code caused by ambiguous data in the National Weather Service CAP feeds. These items should be addressed by NWS by publishing a document that clearly states the behavior for each of these conditions or by generally adding more XML enclosures especially replacing the long list of counties that can occur.
Expired Alerts
Expired alerts contain a valid <event></event> section with <description>alert has expired</description>. There seems to be little else in the document that can be used to determine that the event is basically empty and expired. One option might be to key on a null <expires></expires> section but nothing is guaranteed since this behavior is not documented by the national weather service as far as I can tell.
<event></event>
<description>alert has expired</description>
<expires></expires>
Empty CAP Documents
If there are no notifications for a county or zone, the CAP document will contain a valid <event></event> section where the <id></id> is the same as the CAP URL (i.e. points to its self). Again there is little else in the document that can be used to unambiguously determine that there are no events for that zone or county.
<id></id>
Long Lists of Counties
Events can contain a long list of counties. For anyone trying to perform text to speech or even SMS delivery of the events the text can be too long. Ideally the county list would be in other XML enclosures so that XSL files could still display pages correctly, but other uses would not need to consider the, potentially long list of counties.
Implement point detection based on latitude / longitude
Events contain a <polygon></polygon> that could be used to determine if a specific latitude / longitude is in the event area. This would greatly reduce the number of alerts for a specific point in a county since the NWS has recently started issuing and expiring events for specific areas that are not bound by county. Tracking at the county level can trigger several events over a short period as a storm progresses through the county.
<polygon></polygon>
http://alerts.weather.gov/ - Primary NOAA National Weather Service page for Public Alerts. Has a full list of all county and forecast zone IDs.
http://alerts.weather.gov/cap/product_list.txt - List of possible data that is populated in the <event> field
Michael Stovenour, <michael at stovenour.net>
<michael at stovenour.net>
Please report any bugs or feature requests to bug-weather-noaa-alert at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Weather-NOAA-Alert. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.
bug-weather-noaa-alert at rt.cpan.org
You can find documentation for this module with the perldoc command.
perldoc Weather::NOAA::Alert
You can also look for information at:
RT: CPAN's request tracker (report bugs here)
http://rt.cpan.org/NoAuth/Bugs.html?Dist=Weather-NOAA-Alert
AnnoCPAN: Annotated CPAN documentation
http://annocpan.org/dist/Weather-NOAA-Alert
CPAN Ratings
http://cpanratings.perl.org/d/Weather-NOAA-Alert
Search CPAN
http://search.cpan.org/dist/Weather-NOAA-Alert/
Copyright 2011 Michael Stovenour.
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.
To install Weather::NOAA::Alert, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Weather::NOAA::Alert
CPAN shell
perl -MCPAN -e shell install Weather::NOAA::Alert
For more information on module installation, please visit the detailed CPAN module installation guide.