/ 
Weather-NHC-TropicalCyclone-0.36
/ Weather::NHC::TropicalCyclone

NAME

Weather::NHC::TropicalCyclone - client and object interface for NHC tropical cyclone status data

SYNOPSIS

Fetch the current NHC status feed:

use Weather::NHC::TropicalCyclone ();

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

for my $storm ( @{ $nhc->active_storms } ) {
    printf "%s (%s) - %s\n",
      $storm->name,
      $storm->id,
      $storm->kind;
}

Load an archived CurrentStorms.json without making a network request:

my $nhc = Weather::NHC::TropicalCyclone->new;
$nhc->load_file('CurrentStorms.json');

Or load JSON already held in memory:

$nhc->load_json($json_text);

DESCRIPTION

Weather::NHC::TropicalCyclone reads the National Hurricane Center's CurrentStorms.json status file and exposes each active storm as a Weather::NHC::TropicalCyclone::Storm object.

Version 0.36 separates network access, lightweight feed validation, and storm resource dispatch so those concerns can be tested independently. Existing fetch, storm lookup, RSS, and storm fetch_* methods remain available.

The parser is deliberately tolerant of additive changes to the NHC feed. Fields that this distribution does not yet know about are preserved and reported via "validation_warnings"; they do not cause parsing to fail.

LOADING NHC DATA

fetch

$nhc->fetch;

Fetches $DEFAULT_URL. The historical positional arguments remain supported:

$nhc->fetch(120, '/tmp/CurrentStorms.json');

The preferred form uses named options:

$nhc->fetch(
    timeout => 120,
    save_to => '/tmp/CurrentStorms.json',
);

Supported options are:

  • timeout

    Request timeout in seconds. The default is $DEFAULT_TIMEOUT. A false value disables the alarm-based timeout retained for backward compatibility.

  • save_to

    Save the exact fetched JSON text to this path before parsing it. file is an alias.

  • url

    Override $DEFAULT_URL, useful for mirrors and replay services.

load_json

$nhc->load_json($json_text);

Parses and validates NHC JSON already in memory. This is useful for archived storms, replay systems, and deterministic tests.

load_file

$nhc->load_file('/archive/CurrentStorms.json');

Reads and processes a saved NHC status file.

validate

my $report = $nhc->validate($json_or_hashref);

Returns a hash reference with errors and warnings array references. The validation is intentionally lightweight rather than a full JSON-Schema implementation.

validation_warnings

Returns warnings generated by the most recent successful load. Currently this is primarily used to report previously unknown NHC storm fields that were preserved without interpretation.

ACTIVE STORMS

active_storms

Returns an array reference of Weather::NHC::TropicalCyclone::Storm objects. The array is empty when NHC reports no active storms.

get_storm_ids

Returns an array reference containing the active ATCF/NHC storm identifiers, for example al042026 or cp012026.

get_storm_by_id

my $storm = $nhc->get_storm_by_id('al042026');

Returns the cached storm object or undef when that id is not active.

RSS FEEDS

fetch_rss_atlantic

Fetches the Atlantic basin RSS feed.

fetch_rss_east_pacific

Fetches the Eastern Pacific basin RSS feed.

fetch_rss_central_pacific

Fetches the Central Pacific basin RSS feed.

All three RSS methods fetch the corresponding raw NHC RSS XML. Each accepts an optional filename to which the response will also be written.

TESTING AND CUSTOM HTTP CLIENTS

A HTTP::Tiny-compatible object can be injected into the constructor:

my $nhc = Weather::NHC::TropicalCyclone->new(
    http => $mock_http,
);

The object must provide get and mirror. This is primarily useful for tests, replay systems, and applications that need custom transport behavior.

NHC DATA COMPATIBILITY

NHC documents CurrentStorms.json as a root object containing one activeStorms array, with unavailable products represented by JSON null. The 0.36 parser also reflects observed NHC data through the 2026 season, including Central Pacific CP1-CP5 bin numbers, camelCase latitudeNumeric/longitudeNumeric, and the peakSurgeKML field.

The distribution contains representative offline fixtures. Maintainers can also run xt/archive-compatibility.t against a checkout of the StormSurgeLive/storm-archive repository to exercise the parser against the full historical corpus.

SEE ALSO

Weather::NHC::TropicalCyclone::Storm, Weather::NHC::TropicalCyclone::ForecastAdvisory, Weather::NHC::TropicalCyclone::StormTable, https://www.nhc.noaa.gov/productexamples/, https://www.nhc.noaa.gov/gis/.

LICENSE

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