NAME

Weather::Meteo - Interface to https://open-meteo.com for historical weather data

VERSION

Version 0.12

SYNOPSIS

The Weather::Meteo module provides an interface to the Open-Meteo API for retrieving historical weather data from 1940. It allows users to fetch weather information by specifying latitude, longitude, and a date. The module supports object-oriented usage and allows customization of the HTTP user agent.

  use Weather::Meteo;

  my $meteo = Weather::Meteo->new();
  my $weather = $meteo->weather({ latitude => 0.1, longitude => 0.2, date => '2022-12-25' });

• Caching

  Identical requests are cached (using CHI or a user-supplied caching object), reducing the number of HTTP requests to the API and speeding up repeated queries.

  This module leverages CHI for caching geocoding responses. When a geocode request is made, a cache key is constructed from the request. If a cached response exists, it is returned immediately, avoiding unnecessary API calls.

• Rate-Limiting

  A minimum interval between successive API calls can be enforced to ensure that the API is not overwhelmed and to comply with any request throttling requirements.

  Rate-limiting is implemented using Time::HiRes. A minimum interval between API calls can be specified via the min_interval parameter in the constructor. Before making an API call, the module checks how much time has elapsed since the last request and, if necessary, sleeps for the remaining time.

METHODS

new

my $meteo = Weather::Meteo->new();
my $ua = LWP::UserAgent->new();
$ua->env_proxy(1);
$meteo = Weather::Meteo->new(ua => $ua);

my $weather = $meteo->weather({ latitude => 51.34, longitude => 1.42, date => '2022-12-25' });
my @snowfall = @{$weather->{'hourly'}->{'snowfall'}};

print 'Number of cms of snow: ', $snowfall[1], "\n";

Creates a new instance. Acceptable options include:

• cache

  A caching object. If not provided, an in-memory cache is created with a default expiration of one hour.

• host

  The API host endpoint. Defaults to https://archive-api.open-meteo.com.

• min_interval

  Minimum number of seconds to wait between API requests. Defaults to 0 (no delay). Use this option to enforce rate-limiting.

• ua

  An object to use for HTTP requests. If not provided, a default user agent is created.

weather

use Geo::Location::Point;

my $ramsgate = Geo::Location::Point->new({ latitude => 51.34, longitude => 1.42 });
# Print snowfall at 1AM on Christmas morning in Ramsgate
$weather = $meteo->weather($ramsgate, '2022-12-25');
@snowfall = @{$weather->{'hourly'}->{'snowfall'}};

print 'Number of cms of snow: ', $snowfall[1], "\n";

use DateTime;
my $dt = DateTime->new(year => 2024, month => 2, day => 1);
$weather = $meteo->weather({ location => $ramsgate, date => $dt });

The date argument can be an ISO-8601 formatted date, or an object that understands the strftime method.

Takes an optional argument, tz, containing the time zone. If not given, the module tries to work it out from the given location, for that to work set TIMEZONEDB_KEY to be your API key from https://timezonedb.com. If all else fails, the module falls back to Europe/London.

ua

Accessor method to get and set UserAgent object used internally. You can call env_proxy for example, to get the proxy information from environment variables:

$meteo->ua()->env_proxy(1);

You can also set your own User-Agent object:

use LWP::UserAgent::Throttled;

my $ua = LWP::UserAgent::Throttled->new();
$ua->throttle('open-meteo.com' => 1);
$meteo->ua($ua);

AUTHOR

Nigel Horne, <njh@bandsman.co.uk>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

Lots of thanks to the folks at https://open-meteo.com.

BUGS

This module is provided as-is without any warranty.

Please report any bugs or feature requests to bug-weather-meteo at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Weather-Meteo. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SEE ALSO

Open Meteo API: https://open-meteo.com/en/docs#api_form

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Weather::Meteo

You can also look for information at:

• MetaCPAN

  https://metacpan.org/release/Weather-Meteo

• RT: CPAN's request tracker

  https://rt.cpan.org/NoAuth/Bugs.html?Dist=Weather-Meteo

• CPANTS

  http://cpants.cpanauthors.org/dist/Weather-Meteo

• CPAN Testers' Matrix

  http://matrix.cpantesters.org/?dist=Weather-Meteo

• CPAN Testers Dependencies

  http://deps.cpantesters.org/?module=Weather-Meteo

LICENSE AND COPYRIGHT

Copyright 2023-2025 Nigel Horne.

This program is released under the following licence: GPL2