/ 
NOAA-Aurora-0.1
/ NOAA::Aurora

NAME

NOAA::Aurora - Simple client for NOAA's Aurora Forecast Service

SYNOPSIS

use NOAA::Aurora;

# Constructor can use RFC 3339 or ISO instead of timestamps for timeseries
my $aurora = NOAA::Aurora->new(date_format => 'rfc');

# Save the latest probability map to an image file
$aurora->get_image(hemisphere => 'north', output => 'aurora_north.jpg');

# Get aurora probability for a given location
my $probability = $aurora->get_probability(lat => 51.2, lon => -1.8);

# Get 3-day forecast as a timeseries
my $forecast = $aurora->get_forecast();

# Get 27-day outlook as a timeseries
my $outlook = $aurora->get_outlook();

DESCRIPTION

NOAA::Aurora provides basic access to the NOAA Space Weather Prediction Center (SWPC) Aurora Forecast API. This service provides real-time aurora forecasts based on solar activity and geomagnetic conditions.

The module fetches aurora probability data, latest aurora images, and the 3-day aurora forecast.

Responses are cached (by default for 120 sec).

CONSTRUCTOR

new

  my $aurora = NOAA::Aurora->new(
      cache       => $cache_secs?,
      swpc        => $swpc_services_subdomain,
      date_format => $unix_rfc_or_iso,
      timeout     => $timeout_sec?,
      agent       => $user_agent_string?,
      ua          => $lwp_ua?,
  );

Optional parameters:

  • cache : Will cache results for the specified seconds. Default: 120.

  • swpc : Space Weather Prediction Center subdomain. Default: services.swpc.noaa.gov.

  • date_format : Format for functions that return dates/timestamps. Can be unix (unix timestamp), rfc (for YYYY-MM-DD HH:mm:ssZ) or iso (for YYYY-MM-DDTHH:mm:ssZ). Default: unix.

  • timeout : Timeout for requests in secs. Default: 30.

  • agent : Customize the user agent string.

  • ua : Pass your own LWP::UserAgent to customise further.

Note that the module base is Weather::API::Base, so some additional parameters are inherited - see the base module for details.

METHODS

get_image

my $image_data = $aurora->get_image(
    hemisphere => $hem,
    output     => $filename?
);

Returns the latest aurora oval image for the specified hemisphere in jpg data. Optionally will save it to $filename. Function caches the results (see constructor).

Optional parameters:

  • hemisphere : north or south (accepts abbreviations). Default: north.

  • output : If specified will save to specified jpg file.

get_probability

my $probability = $aurora->get_probability(
    lat  => $lat,
    lon  => $lon,
    hash => $return_hash?
);

Fetches the aurora probability at a specific latitude and longitude if specified, otherwise will return all the globe. Can return the original NOAA JSON string, or decode it into a Perl hash of hashes:

{
    $longitude1 => {$latitude1 => $prob},
    ...
}

Probability given as an integer percentage value (0-100). Granularity is 1 degree. In Perl hash mode, 0 probability locations will be ommitted from the response.

The function caches the results (see constructor), so subsequent calls will not require downloading and decoding.

Optional parameters:

  • hash : If true, will return Perl hash instead of JSON.

get_forecast

my $forecast = $aurora->get_forecast(
    format => $output?
);

Retrieves NOAA's 3-day space forecast (preferred over the geomagnetic forecast due to more frequent / twice daily update) and by default returns an arrayref of hashes:

[{time => $timestamp, kp => $kp_value},...]

The timestamp will be at the start of the 3h time range NOAA returns.

Optional parameters:

  • format : If 'text' is specified as the format, raw text output will be returned instead of an array with the timeseries.

get_outlook

my $outlook = $aurora->get_outlook(
    format => $output?
);

Retrieves NOAA's 27-day outlook with the forecasted daily values for the 10.7cm Solar radio flux, the Planetary A Index and the largest Kp index. By default returns an arrayref of hashes:

[
  {
    time => $timestamp,
    flux => $flux_value,
    ap   => $a_index,
    kp   => $max_kp_value
  }, ...
]

  • format : If 'text' is specified as the format, raw text output will be returned instead of an array with the timeseries.

UTILITY FUNCTIONS

kp_to_g

my $g_index = kp_to_g($kp_index);

Pass the Kp index and get the G-Index (Geomagnetic storm from G1 to G5) or 0 if the Kp is not indicative of a Geomagnetic Storm. Fractional kp is rounded half up (e.g. kp >= 4.5 -> G1).

AUTHOR

Dimitrios Kechagias, <dkechag at cpan.org>

BUGS

Please report any bugs or feature requests either on GitHub (preferred), or on RT (via the email bug-noaa-aurora at rt.cpan.org or web interface).

GIT

https://github.com/dkechag/NOAA-Aurora

LICENSE AND COPYRIGHT

This software is copyright (c) 2025 by Dimitrios Kechagias.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.