• ForecastIO.pm
• Perl Module
• Usage
• Alerts
• Current Conditions
• Forecast - Next 48 Hours
• Forecast - Next 60 Minutes
• Forecast - Next 7 Days
• Additional Info
• Utilities
• format_date

Perl ForecastIO module README for GitHub

ForecastIO.pm

This Perl wrapper API is used to process the excellent weather data, provided in JSON format by forecast.io.

Related: forecast.io developer API info. From the forecast.io website:

"The easiest, most advanced, weather API on the web. The same API that powers Forecast.io and Dark Sky for iOS can provide accurate short­term and long­term weather predictions to your business, application, or crazy idea."

A working example that uses this Perl module can be found at Toledo Weather. This weather Web app uses jQuery mobile on the client side. Several Perl scripts execute at different intervals in cron that fetch RSS, custom XML, and HTML files from the National Weather Service to provide the data for display. The forecast.io section of this Web app uses a small part of this Perl module. Code for the entire Toledo weather Web app exists on GitHub at ToledoWX.

Perl Module

This ForecastIO.pm Perl module was inspired by the PHP forecast.io wrapper located at tobias-redmann/forecast.io-php-api.

Usage

View the test Perl script in the bin directory.

Also, view the output file, created by the above test script.

Include the module in your program.

perl use ForecastIO;

Create the forecast object and set API key and location.

perl my $forecast = ForecastIO->new($api_key, $latitude, $longitude);

Download JSON data and convert it to a Perl hash.

perl $forecast->fetch_data;

Alerts

Forecast.io data includes special weather statements, watches, and warnings that have been issued by the National Weather Service, such as Severe Thunderstorm Warning, Heat Advisory, etc.

my @alerts = $forecast->alerts;
if ( @alerts ) {  
    foreach my $a ( @alerts ) {  
        # loop through the array of objects and 
        # use get methods to process data for 
        # each object ``$a`` in the array. Example:


    }  
}  

Get methods:

$a->alert_title $a->alert_uri $a->alert_expires $a->alert_description

Current Conditions

Get the object for the current conditions.

perl my $currently = $forecast->currently;

Get methods available for the currently object:

perl $currently->time
$currently->summary
$currently->icon
$currently->temperature
$currently->dewPoint
$currently->windBearing
$currently->windSpeed
$currently->pressure
$currently->humidity
$currently->ozone
$currently->precipProbability
$currently->cloudCover
$currently->cloudCover
$currently->precipIntensity
$currently->precipType
$currently->visibility

Forecast - Next 48 Hours

Return an array of hourly objects, which contain the following forecast information for each hour up to 48 hours: time, icon, temperature, pressure, wind direction, and wind speed.

my @hourly = $forecast->hourly;
if ( @hourly ) {
    foreach my $h ( @hourly ) {
        print ForecastIOUtils::format_date( $h->time ) .  
        " : icon =  "             . $h->icon .  
        " : temp = "              . ForecastIOUtils::round($h->temperature) . 
        " : precip type =  "      . $h->precipType.  
        " : pressure = "          . ForecastIOUtils::millibars_to_inches($h->pressure) . " in. " .
        " : wind direction = "    . ForecastIOUtils::degrees_to_cardinal($h->windBearing) .  
        " : wind speed = "        . ForecastIOUtils::round($h->windSpeed) . " mph " .  
        "\n";
    }
}

Forecast - Next 60 Minutes

Return an array of minutely objects, which contain the following forecast information for each minute for the next 60 minutes: time and precipitation probability, intensity, and type.

my @minutely = $forecast->minutely;
if ( @minutely ) {
    foreach my $m ( @minutely ) {
        print ForecastIOUtils::format_date( $m->time ) . 
        " : " . $m->precipProbability * 100 . "% chance " .  
        " : " . ForecastIOUtils::calc_intensity($m->precipIntensity) . 
        " : " . $m->precipType . "\n";
    }
}

Forecast - Next 7 Days

Return an array of daily objects, which contain the following forecast information for each day for the next seven days: time, sunrise time, sunset time, cloud cover, min temp and min temp time, max temp and max temp time, wind speed, wind direction, and precipitation type, max intensity, and max intensity time.

my @daily = $forecast->daily;
if ( @daily ) {
    foreach my $d ( @daily ) {
        # loop through the array of objects and 
        # use get methods to process data for 
        # each object ``$d`` in the array. Example:
        print "precip accumulation = " . $d->precipAccumulation . "\n";
    }
}

Get methods

$d->time
$d->icon
$d->sunriseTime
$d->sunsetTime
$d->cloudCover
$d->precipType
$d->precipIntensityMax
$d->precipIntensityMaxTime
$d->precipAccumulation
$d->temperatureMin
$d->temperatureMinTime
$d->temperatureMax
$d->temperatureMaxTime
$d->windSpeed
$d->windBearing

Additional Info

The very detailed forecast.io JSON data set contains other information. Review the current API doc for details https://developer.forecast.io/docs/v2.

The ForecastIO.pm provides get methods for the forecast object to access some of this additional info:

$forecast->offset # timezone offset
$forecast->timezone
$forecast->hourlysummary
$forecast->dailysummary
$forecast->minutelysummary

Utilities

I like the raw data provided by forecast.io. It provides the user or developer with options on how to display the data. Some of the forecast.io data needs additional processing or formatting to display it in a more "normal" way. The ForecastIO.pm module also contains a utilities package.

Each subroutine is preceded by ForecastIOUtils::

perl format_date($currently->time)
degrees_to_cardinal($currently->windBearing)
round($currently->windSpeed)
round($currently->temperature)
round($currently->dewPoint)
millibars_to_inches($currently->pressure)
cloud_cover_description($currently->cloudCover)
calc_intensity($currently->precipIntensity)
calc_intensity_color($currently->precipIntensity)

format_date

Forecast.io contains date and time in epoch seconds. The format_date subroutine returns info in the format as: 2013-07-10T17:57:36Z which is ISO 8601 format.

If no epoch seconds are passed to subroutine, then format_date returns the current date and time.

You can modify the format_date subroutine to produce a different format. And you can play with the precipitation intensity subroutine to produce text values that seem more appropriate with your own observations. Thus far, I think the text-based intensity values returned in this module match my observations in Toledo, Ohio.