NAME

Weather::NHC::TropicalCyclone::Storm - Provides a convenient interface to individual storm sections delivered inside of the NHC Tropical Cyclone JSON file.

SYNOPSIS

use strict;
use warnings;
use Weather::NHC::TropicalCyclone ();

my $nhc = Weather::NHC::TropicalCyclone->new;
$nhc->fetch;

my $storms_ref = $nhc->active_storms;
my $count = @$storms_ref;

print qq{$count storms found\n};

foreach my $storm (@$storms_ref) {
  print $storm->name . qq{\n};
  my ($text, $advNum, $local_file) = $storm->fetch_publicAdvisory($storm->id.q{.fst});
  print qq{$local_file saved for Advisory $advNum\n};
  rename $local_file, qq{$advNum.$local_file};
}

DESCRIPTION

Given JSON returned by the NHC via https://www.nhc.noaa.gov/CurrentStorms.json, this module creates a covenient object for encapsulating each storm and fetching the data associated with them.

METHODS

Each storm instances provides an accessor for each field. In addition to this, each field that represents data (text extractible via .shtml or a downloadable file) also provides a fetch_* method.

Text Extracted from .shtml

Optional parameter naming a file to save the extracted text to.

Returns a list of 3 values: extracted text, advisory number, and local file (if optional parameter is provided to the called method.

Provided methods include:

fetch_publicAdvisory

fetch_forecastAdvisory

fetch_forecastDiscussion

fetch_windspeedProbabilities

_get_text

Internal method used by all of the fetch methods that extract text from the linked .shtml files.

Directly Downloadable Files

Optional parameter naming a file to save the extracted text to.

Returns a list of 2 values: name of saved local file and advisory (if provided).

Provided methods include:

fetch_forecastTrack

fetch_windWatchesWarnings

fetch_trackCone

fetch_initialWindExtent

fetch_forecastWindRadiiGIS

fetch_earliestArrivalTimeTSWindsGIS

fetch_mostLikelyTimeTSWindsGIS

fetch_windSpeedProbabilitiesGIS

fetch_stormSurgeWatchWarningGIS

fetch_potentialStormSurgeFloodingGIS

fetch_bestTrackGIS

Note: This resource doesn't provide an advisory. N/A is returned in its place.

_get_file

Internal method used by all of the fetch methods that downloads files.

Auxillary Methods

fetch_forecastAdvisory_as_atcf

An optional parameter may be passed that designates a file in which to save the forecast advisory in ATCF format. Returns a list, item 1 is the array reference containing the ATCF data; if the optional file name was passed, the same value is passed. If no local file name is passed, this value with be undef.

# to get $atcf_ref without saving to a file
my ($atcf_ref, $advNum_atcf, $saved_file) = $storm->fetch_forecastAdvisory_as_atcf($file);

# to save ATCF format to a file
my $file = q{my.fst};
my ($atcf_ref, $advNum_atcf, $saved_file) = $storm->fetch_forecastAdvisory_as_atcf($file);

Fetches the forecast advisory, converts the forecast advisory into ATCF format, then returns an array reference containing each full ATCF record as an element in the array reference.

This method internally uses <fetch_forecastAdvisory> without an intermediate file save, the uses methods provided by the provide module, Weather::NHC::TropicalCyclone::ForecastAdvisory.

fetch_forecastGraphics_urls

Uses the URL provided by the forecastGraphics fields to determine the location of the base graphics directory. The default index page returned by the web server is scraped to get a fully resolved list of all graphics available for the storm.

Returns list of graphics URLs as an array reference. A method to download all of the graphics is not provided at this time. But give the list of URLs, it's trivial to write a loop to download any number of these images using HTTP::Tiny's mirror method. See perldoc HTTP::Tiny for more information.

If the base directory for the image URLs can't be determined, this method returns an empty array reference. It is up to the caller to determine that none were returned.

fetch_best_track

Accepts an optional parameter that defines the local file to save this file as.

Attempts to fetch the best track .dat file that. This URL is not provided directly by the JSON file, but can be easily derived by using using $DEFAULT_BTK_ROOT and composing the filename using the id accessor. This method combines this with a fetch over HTTPS (using HTTP::Tiny's mirror method).

This method returns just the local file name.

kind

Returns a Human meaningful name for the kind of storm is represented by the reference. Based on the specification, the following kinds are returned based on the classification value:

NHC |     Meaningful Kind
--- | -------------------------------------
TD  | Tropical Depression
STD | Subtropical Depression
TS  | Tropical Storm
HU  | Hurricane
STS | Subtropical Storm
PTC | Post-tropical Cyclone / Remnants
TY  | Typhoon (we don't use this currently)
PC  | Potential Tropical Cyclone

ENVIRONMENT

Default ackage variables:

$DEFAULT_GRAPHICS_ROOT

defines the base URL used to determine the list of graphics available for the storm

$DEFAULT_BTK_ROOT

defines the base URL used to fetch the best track .dat file

COPYRIGHT and LICENSE

This module is distributed under the same terms as Perl itself.