NAME

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

VERSION

Version 0.01

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
          },
          {...},
          ...
      ]
  };

DESCRIPTION

Weather::Astro7Timer provides basic access to the 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 official API documentation and GitHub Wiki for details.

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

CONSTRUCTOR

new

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

Optional parameters:

• scheme : You can specify http. Default: https.

• timeout : Timeout for requests in secs. Default: 30.

• agent : Customize the user agent string.

• ua : Pass your own LWP::UserAgent to customise further.

METHODS

get

    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 JSON or XML::Simple to decode it directly to a Perl hash. For an explanation to the returned data, refer to the official API documentation.

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

Required parameters:

• lat : Latitude (-90 to 90). South is negative.

• lon : Longitude (-180 to 180). West is negative.

• product : Choose from the available forecast products:

  • astro : ASTRO 3-day forecast for astronomy/stargazing with 3h step (includes astronomical seeing, transparency).

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

  • civillight : CIVIL Light simplified per-day forecast for next week.

  • meteo : A detailed meteorogical forecast including relative humidity and wind profile from 950hPa to 200hPa.

  • two : A two week overview forecast.

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

• lang : Supports zh-CN or zh-TW, otherwise default is en.

• unit : metric (default) or british units.

• output : Output format, supports json (default) or xml, although internal will also work, returning png image.

• tzshift : Timezone offset in hours ( -23 to 23).

• ac : Altitude correction (e.g. temp) for high peaks. Default 0, accepts 2 or 7 (in km). Only for astro product.

get_response

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

Same as get except it returns the full HTTP::Response from the API (so you can handle bad requests yourself).

CONVENIENCE FUNCTIONS

products

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

Returns the supported forecast products.

AUTHOR

Dimitrios Kechagias, <dkechag at cpan.org>

BUGS

Please report any bugs or feature requests either on GitHub (preferred), or on RT (via the email bug-weather-astro7timer at rt.cpan.org or web interface).

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

GIT

https://github.com/dkechag/Weather-Astro7Timer

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.

cpanm Weather::Astro7Timer

perl -MCPAN -e shell
install Weather::Astro7Timer