Perl ForecastIO module README for GitHub

markdown=yes

# ForecastIO.pm

This Perl wrapper API is used to process weather data that is provided in JSON format by [forecast.io](http://forecast.io/).

Related: [forecast.io developer API info](https://developer.forecast.io). 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](http://toledotalk.com/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](https://github.com/jrsawvel/ToledoWX).

# Perl Module

This Perl module was inspired by the PHP forecast.io wrapper located at [tobias-redmann/forecast.io-php-api](https://github.com/tobias-redmann/forecast.io-php-api).

## Usage

View the [test Perl script](https://github.com/jrsawvel/Perl-ForecastIO/blob/master/bin/test-forecastio-1.pl) in the bin directory.


```perl
use ForecastIO;
```

Set your 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;
```

### 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  
```

### Current Conditions Utilities

Some of the forecast.io data needs additional processing or formatting to display it in a more meaningful way. The ForecastIO.pm module also contains a utilities package.

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