/ 
Weather-Astro7Timer-0.3
River stage zero No dependents
/ Weather::Astro7Timer

NAME

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

SYNOPSIS

use Weather::Astro7Timer;

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

# Get ASTRO weather for the Stonehenge area

my %report = $w7t->get(
    product => 'astro',    # Forecast type (astro, civil, civillight, meteo)
    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
        },
        {...},
        ...
    ]
};

# You can get a png image instead...

my $data = $w7t->get(
    product => 'civil',
    lat     => 51.2,
    lon     => -1.8,
    output  => 'png'
);

# ... and write it out to a file
open(my $fh, '>', "civil.png") or die $!; print $fh $data; close($fh);

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 (in the case of png output, the hash will containg a single key data with the png data). 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 (may be unmaintained).

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), xml or png.

  • 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.

HELPER FUNCTIONS

init_to_ts

my $timestamp = Weather::Astro7Timer::init_to_ts($report{init});

Returns a unix timestamp from the init date. For the subsequent entries of the timeseries you can add timepoint * 3600 to the timestamp.

ts_to_date

my $datetime = Weather::Astro7Timer::ts_to_date($timestamp, $utc?);

For convenience, ts_to_date will convert a timestamp (e.g. returned by init_to_ts) to a date/time format YYYY-MM-DD HH:mm:ss in your local time zone, or YYYY-MM-DD HH:mm:ssZ in UTC if the second argument is true. For example:

my $datetime = Weather::Astro7Timer::ts_to_date(
   Weather::Astro7Timer::init_to_ts($report{init}) +
       $report{dataseries}->[0]->{timepoint} * 3600
);

OTHER PERL WEATHER MODULES

A quick listing of Perl modules for current weather and forecasts from various sources:

OpenWeatherMap

OpenWeatherMap uses various weather sources combined with their own ML and offers a couple of free endpoints (the v2.5 current weather and 5d/3h forecast) with generous request limits. Their newer One Call 3.0 API also offers some free usage (1000 calls/day) and the cost is per call above that. If you want access to history APIs, extended hourly forecasts etc, there are monthly subscriptions. Weather::OWM is from the same author as this module and simplar in use.

Apple WeatherKit

An alternative source for multi-source forecasts is Apple's WeatherKit (based on the old Dark Sky weather API). It offers 500k calls/day for free, but requires a paid Apple developer account. You can use Weather::WeatherKit, which is very similar to this module (same author).

YR.no

Finally, the Norwegian Meteorological Institute offers the free YR.no service, which can be accessed via Weather::YR, although I am not affiliated with that module.

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.