# 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
=> $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 <[email protected]>

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.