File Coverage

blib/lib/Weather/Astro7Timer.pm

Criterion	Covered	Total	%
statement	60	60	100.0
branch	20	20	100.0
condition	16	17	94.1
subroutine	10	10	100.0
pod	4	4	100.0
total	110	111	99.1

package Weather::Astro7Timer;

use 5.006;
use strict;
use warnings;

use Carp;

=head1 NAME

Weather::Astro7Timer - Simple client for the 7Timer.info Weather Forecast service

=head1 VERSION

Version 0.01

=cut

our $VERSION = '0.1';

=head1 SYNOPSIS

  my $w7t = Weather::Astro7Timer->new();

  # Get ASTRO weather for the Stonehenge area

  my %report = $w7t->get(
      product => 'astro',    # Forecast type (astro, civil, civillight, meteo, two)
      lat     => 51.2,       # Latitude
      lon     => -1.8,       # Longitude
  );

  # Dumping the result would give you:
  %report = {
      'product'    => 'astro',
      'init'       => '2023032606',
      'dataseries' => [{
              'temp2m'  => 6,
              'wind10m' => {
                  'speed'     => 2,
                  'direction' => 'NE'
              },
              'rh2m'         => 13,
              'seeing'       => 3,
              'timepoint'    => 3,
              'lifted_index' => 2,
              'prec_type'    => 'none',
              'cloudcover'   => 9,
              'transparency' => 6
          },
          {...},
          ...
      ]
  };

=head1 DESCRIPTION

Weather::Astro7Timer provides basic access to the L<7Timer.info|https://7Timer.info>
Weather Forecast API.
7Timer is a service based on NOAA's GFS and provides various types of forecast products.
It is mostly known for its ASTRO product intended for astronomers and stargazers, as
it provides an astronomical seeing and transparency forecast.

Pease see the L and
L for details.

The module was made to serve the apps L and
L, but if your service
requires some extra functionality, feel free to contact the author about it.

=head1 CONSTRUCTOR

=head2 C

    my $w7t = Weather::Astro7Timer->new(
        scheme  => $http_scheme?,
        timeout => $timeout_sec?,
        agent   => $user_agent_string?,
        ua      => $lwp_ua?,
    );

Optional parameters:

=over 4

=item * C : You can specify C. Default: C.

=item * C : Timeout for requests in secs. Default: C<30>.

=item * C : Customize the user agent string.

=item * C : Pass your own L to customise further.

=back

=head1 METHODS

=head2 C

    my $report = $w7t->get(
        product => $product,   # Forecast type (astro, civil, civillight, meteo, two)
        lat     => $lat,       # Latitude
        lon     => $lon,       # Longitude
        output  => $format?,   # Output format (default json)
        unit    => $unit?,     # Units (default metric)
        lang    => $language?, # Language (default en)
        tzshift => $tz_shift?, # Timezone shift from UTC (hours, default 0)
        ac      => $alt_cor?,  # Altitude correction (default 0)
    );

    my %report = $w7t->get( ... );


Fetches a forecast report for the requested for the requested location.
Returns a string containing the JSON or XML data, except in array context, in which case,
as a convenience, it will use L or L to decode it directly to a Perl hash.
For an explanation to the returned data, refer to the L.

If the request is not successful, it will C throwing the C<< HTTP::Response->status_line >>.

Required parameters:

=over 4

=item * C : Latitude (-90 to 90). South is negative.

=item * C : Longitude (-180 to 180). West is negative.

=item * C : Choose from the available forecast products:

=over 4

=item * C : ASTRO 3-day forecast for astronomy/stargazing with 3h step (includes astronomical seeing, transparency).

=item * C : CIVIL 8-day forecast that provides a weather type enum (see docs for equivalent icons) with 3h step.

=item * C : CIVIL Light simplified per-day forecast for next week.

=item * C : A detailed meteorogical forecast including relative humidity and wind profile from 950hPa to 200hPa.

=item * C : A two week overview forecast.

=back

=back

Optional parameters (see the API documentation for further details):

=over 4

=item * C : Supports C or C, otherwise default is C.

=item * C : C (default) or C units.

=item * C : Output format, supports C (default) or C, although
C will also work, returning png image.

=item * C : Timezone offset in hours ( -23 to 23).

=item * C : Altitude correction (e.g. temp) for high peaks. Default C<0>, accepts
C<2> or C<7> (in km). Only for C product.

=back

=head2 C

    my $response = $w7t->get_response(
        lat     => $lat,
        lon     => $lon,
        product => $product
        %args?
    );

Same as C except it returns the full L from the API (so you
can handle bad requests yourself).


=head1 CONVENIENCE FUNCTIONS

=head2 C

    my @products = Weather::Astro7Timer::products();

Returns the supported forecast products.

=cut

sub new {
    my $class = shift;

    my $self = {};
    bless($self, $class);

    my %args = @_;

    $self->{ua}      = $args{ua};
    $self->{scheme}  = $args{scheme} || 'https';
    $self->{timeout} = $args{timeout} || 30;
    $self->{agent}   = $args{agent} || "libwww-perl Weather::Astro7Timer/$VERSION";

    return $self;
}

sub get {
    my $self = shift;
    my %args = @_;
    $args{lang}   ||= 'en';
    $args{output} ||= 'json';

    my $resp = $self->get_response(%args);

    if ($resp->is_success) {
        return _output($resp->decoded_content, wantarray ? $args{output} : '');
    }
    else {
        die $resp->status_line;
    }
}

sub get_response {
    my $self = shift;
    my %args = @_;

    croak("product was not defined")
        unless $args{product};

    croak("product not supported")
        unless grep { /^$args{product}$/ } products();

    croak("lat between -90 and 90 expected")
        unless defined $args{lat} && abs($args{lat}) <= 90;

    croak("lon between -180 and 180 expected")
        unless defined $args{lon} && abs($args{lon}) <= 180;

    my $url = $self->_weather_url(%args);

    unless ($self->{ua}) {
        require LWP::UserAgent;
        $self->{ua} = LWP::UserAgent->new();
    }

    $self->{ua}->agent($self->{agent});
    $self->{ua}->timeout($self->{timeout});

    return $self->{ua}->get($url);
}

sub _weather_url {
    my $self = shift;
    my %args = @_;
    my $prod = delete $args{product};
    my $url =
          $self->{scheme}
        . "://www.7timer.info/bin/$prod.php?"
        . join("&", map {"$_=$args{$_}"} keys %args);

    return $url;
}

sub _output {
    my $str    = shift;
    my $format = shift;

    return $str unless $format;

    if ($format eq 'json') {
        require JSON;
        return %{JSON::decode_json($str)};
    } elsif ($format eq 'xml') {
        require XML::Simple;
        return %{XML::Simple::XMLin($str)};
    }
    return (data => $str);
}

sub products {
    return qw/astro two civil civillight meteo/;
}

=head1 AUTHOR

Dimitrios Kechagias, C<<  >>

=head1 BUGS

Please report any bugs or feature requests either on L (preferred), or on RT (via the email
C or L).

I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

=head1 GIT

L

=head1 LICENSE AND COPYRIGHT

This software is copyright (c) 2023 by Dimitrios Kechagias.

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

=cut

1;