# NAME

Weather::OpenWeatherMap - Interface to the OpenWeatherMap API

# SYNOPSIS

    use Weather::OpenWeatherMap;

    my $api_key = 'foo';

    my $wx = Weather::OpenWeatherMap->new(
      api_key => $api_key,
    );

    # Current conditions:
    my $current = $wx->get_weather(
      location => 'Manchester, NH',
    );
    my $tempf = $current->temp_f;
    my $wind  = $current->wind_speed_mph;
    # (see Weather::OpenWeatherMap::Result::Current)

    # Forecast conditions:
    my $forecast = $wx->get_weather(
      location => 'Manchester, NH',
      forecast => 1,
      days     => 3,
    );
    for my $day ($forecast->list) {
      my $date    = $day->dt->mdy;
      my $temp_lo = $day->temp_min_f,
      my $temp_hi = $day->temp_max_f,
      # (see Weather::OpenWeatherMap::Result::Forecast::Day)
    }
    # (see Weather::OpenWeatherMap::Result::Forecast)

# DESCRIPTION

An object-oriented interface to retrieving weather conditions & forecasts from
__OpenWeatherMap__ ([http://www.openweathermap.org/](http://www.openweathermap.org/)) for a given city,
latitude/longitude, or OpenWeatherMap city code.

This module provides a simple blocking ([LWP::UserAgent](http://search.cpan.org/perldoc?LWP::UserAgent)) interface to
weather retrieval; if you have an event loop handy, the included
[Weather::OpenWeatherMap::Request](http://search.cpan.org/perldoc?Weather::OpenWeatherMap::Request) & [Weather::OpenWeatherMap::Result](http://search.cpan.org/perldoc?Weather::OpenWeatherMap::Result)
classes can be used to create appropriate [HTTP::Request](http://search.cpan.org/perldoc?HTTP::Request) instances and parse
responses from non-blocking HTTP clients.

## ATTRIBUTES

### api\_key

Your [OpenWeatherMap](http://www.openweathermap.org/) API key.

(See [http://www.openweathermap.org/api](http://www.openweathermap.org/api) to register for free.)

### ua

The [LWP::UserAgent](http://search.cpan.org/perldoc?LWP::UserAgent) instance used to issue HTTP requests; can be used to
control LWP options:

    my $wx = Weather::OpenWeatherMap->new(
      api_key => $my_api_key,
      ua => LWP::UserAgent->new(%lwp_opts),  
    );

## METHODS

### get\_weather

    $wx->get_weather(
      # 'location =>' is mandatory.
      #  These are all valid location strings:
      #  By name:
      #   'Manchester, NH'
      #   'London, UK'
      #  By OpenWeatherMap city code:
      #   5089178
      #  By latitude/longitude:
      #   'lat 42, long -71'
      location => 'Manchester, NH',

    # Set 'forecast => 1' to get the forecast,
    # omit or set to false for current weather:
    forecast => 1,

    # If 'forecast' is true, you can specify the number of days to fetch
    # (up to 14):
    days => 3,

      # Optional tag for identifying the response to this request:
      tag  => 'foo',
    );

Request a weather report for the given `location =>`.

The location can be a 'City, State' or 'City, Country' string, an
[OpenWeatherMap](http://www.openweathermap.org/) city code, or a 'lat X, long
Y' string.

Requests the current weather by default (see
[Weather::OpenWeatherMap::Request::Current](http://search.cpan.org/perldoc?Weather::OpenWeatherMap::Request::Current)).

If passed `forecast => 1`, requests a weather forecast (see
[Weather::OpenWeatherMap::Request::Forecast](http://search.cpan.org/perldoc?Weather::OpenWeatherMap::Request::Forecast)), in which case `days
=> $count` can be specified (up to 14).

Any extra arguments are passed to the constructor for the appropriate Request
subclass; see [Weather::OpenWeatherMap::Request](http://search.cpan.org/perldoc?Weather::OpenWeatherMap::Request).

# AUTHOR

Jon Portnoy <avenj@cobaltirc.org>
