# NAME

POEx::Weather::OpenWeatherMap - POE-enabled OpenWeatherMap client

# SYNOPSIS

    use POE;
    use POEx::Weather::OpenWeatherMap;

    # An API key can be obtained (free) at http://www.openweathermap.org:
    my $api_key = 'foo';

    POE::Session->create(
      package_states => [
        main => [qw/
          _start
          
          pwx_error
          pwx_weather
          pwx_forecast
        /],
      ],
    );

    sub _start {
      my ($kernel, $heap) = @_[KERNEL, HEAP];
      
      # Create, store, and start emitter:
      my $wx = POEx::Weather::OpenWeatherMap->new(
        api_key      => $api_key,
        event_prefix => 'pwx_',
      );

      $heap->{wx} = $wx;
      $wx->start;

      ## An example request:
      $wx->get_weather(
        location => 'Manchester, NH',
        tag      => 'mytag',
      );
    }

    sub pwx_error {
      my $err = $_[ARG0];
      my $status  = $err->status;
      my $request = $err->request;
      # ... do something with error ...
      warn "Error! ($status)";
    }

    sub pwx_weather {
      my $result = $_[ARG0];

      my $tag = $result->request->tag;

      my $place = $result->name;

      my $tempf = $result->temp_f;
      my $conditions = $result->conditions_verbose;
      # (see Weather::OpenWeatherMap::Result::Current for a method list)
      # ...
    }

    sub pwx_forecast {
      my $result = $_[ARG0];

      my $place = $result->name;

      my $itr = $result->iter;
      while (my $day = $itr->()) {
        my $date = $day->dt->mdy;
        my $temp_hi = $day->temp_max_f;
        my $temp_lo = $day->temp_min_f;
        # (see Weather::OpenWeatherMap::Result::Forecast)
        # ...
      }
    }

    POE::Kernel->run;

# DESCRIPTION

A POE-enabled interface to OpenWeatherMap ([http://www.openweathermap.org](http://www.openweathermap.org)),
providing an object-oriented asynchronous interface to current & forecast
weather conditions for a given city, latitude/longitude, or OpenWeatherMap
city code.

This is really just an asynchronous counterpart to [Weather::OpenWeatherMap](https://metacpan.org/pod/Weather::OpenWeatherMap);
look there for documentation regarding Request & Result objects.

This an event emitter that consumes [MooX::Role::POE::Emitter](https://metacpan.org/pod/MooX::Role::POE::Emitter); look there
for documentation on composed methods. See [http://www.openweathermap.org](http://www.openweathermap.org)
for more on OpenWeatherMap itself.

## 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.)

`api_key` can be set after object construction via **set\_api\_key**; if the key
is not valid, requests will likely fail with `401 Unauthorized` errors.

### cache

A boolean value indicating whether successful results should be cached to disk
via [Weather::OpenWeatherMap::Cache](https://metacpan.org/pod/Weather::OpenWeatherMap::Cache).

Defaults to false. This may change in a future release.

### cache\_dir

The directory in which cache files are saved. The default may be fine; see
[Weather::OpenWeatherMap::Cache](https://metacpan.org/pod/Weather::OpenWeatherMap::Cache).

### cache\_expiry

The duration (in seconds) for which cache files are considered valid. The
default may be fine; see [Weather::OpenWeatherMap::Cache](https://metacpan.org/pod/Weather::OpenWeatherMap::Cache).

## METHODS

### start

Start our session.

Must be called before events will be received or emitted.

### stop

Stop our session, shutting down the emitter and user agent (which will cancel
pending requests).

### 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](https://metacpan.org/pod/Weather::OpenWeatherMap::Request::Current)).

If passed `forecast => 1`, requests a weather forecast (see
[Weather::OpenWeatherMap::Request::Forecast](https://metacpan.org/pod/Weather::OpenWeatherMap::Request::Forecast)), in which case `days
&#x3d;> $count` can be specified (up to 14). If `hourly => 1` is also
specified, an hourly (rather than daily) report is returned; see
the documentation for [Weather::OpenWeatherMap](https://metacpan.org/pod/Weather::OpenWeatherMap) for details.

If passed `find => 1`, requests search results for a given location name
or latitude & longitude; see [Weather::OpenWeatherMap::Request::Find](https://metacpan.org/pod/Weather::OpenWeatherMap::Request::Find).

An optional `tag =>` can be specified to identify the response when it
comes in.

Any extra arguments are passed to the constructor for the appropriate Request
subclass; see [Weather::OpenWeatherMap::Request](https://metacpan.org/pod/Weather::OpenWeatherMap::Request).

The request is made asynchronously and a response (or error) emitted when it
is available; see ["EMITTED EVENTS"](#emitted-events). There is no useful return value.

## RECEIVED EVENTS

### get\_weather

    $poe_kernel->post( $wx->session_id =>
      get_weather =>
        location => 'Manchester, NH',
        tag      => 'foo',
    );

POE interface to the ["get\_weather"](#get_weather) method; see ["METHODS"](#methods) for available
options.

## EMITTED EVENTS

### error

Emitted when an error occurs; this may be an internal error, an HTTP error,
or an error reported by the OpenWeatherMap API.

`$_[ARG0]` is a [Weather::OpenWeatherMap::Error](https://metacpan.org/pod/Weather::OpenWeatherMap::Error) object.

### weather

Emitted when a request for the current weather has been successfully processed.

`$_[ARG0]` is a [Weather::OpenWeatherMap::Result::Current](https://metacpan.org/pod/Weather::OpenWeatherMap::Result::Current) object; see
that module's documentation for details on retrieving weather information.

### forecast

Emitted when a request for a weather forecast has been successfully processed.

`$_[ARG0]` is a [Weather::OpenWeatherMap::Result::Forecast](https://metacpan.org/pod/Weather::OpenWeatherMap::Result::Forecast) object;
see that module's documentation for details on retrieving daily or hourly forecasts
([Weather::OpenWeatherMap::Result::Forecast::Day](https://metacpan.org/pod/Weather::OpenWeatherMap::Result::Forecast::Day) &
[Weather::OpenWeatherMap::Result::Forecast::Hour](https://metacpan.org/pod/Weather::OpenWeatherMap::Result::Forecast::Hour) objects) from the retrieved
forecast.

# SEE ALSO

[Weather::OpenWeatherMap](https://metacpan.org/pod/Weather::OpenWeatherMap)

[Weather::OpenWeatherMap::Error](https://metacpan.org/pod/Weather::OpenWeatherMap::Error)

[Weather::OpenWeatherMap::Result](https://metacpan.org/pod/Weather::OpenWeatherMap::Result)

[Weather::OpenWeatherMap::Result::Current](https://metacpan.org/pod/Weather::OpenWeatherMap::Result::Current)

[Weather::OpenWeatherMap::Result::Forecast](https://metacpan.org/pod/Weather::OpenWeatherMap::Result::Forecast)

[Weather::OpenWeatherMap::Request](https://metacpan.org/pod/Weather::OpenWeatherMap::Request)

[Weather::OpenWeatherMap::Request::Current](https://metacpan.org/pod/Weather::OpenWeatherMap::Request::Current)

[Weather::OpenWeatherMap::Request::Forecast](https://metacpan.org/pod/Weather::OpenWeatherMap::Request::Forecast)

The `examples/` directory of this distribution.

# AUTHOR

Jon Portnoy <avenj@cobaltirc.org>
