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