view release on metacpan or  search on metacpan

lib/Weather/WeatherKit.pm  view on Meta::CPAN

package Weather::WeatherKit;

use 5.008;
use strict;
use warnings;

use Carp;
use Crypt::JWT qw(encode_jwt);

use parent 'Weather::API::Base';
use Weather::API::Base qw(:all);

=head1 NAME

Weather::WeatherKit - Apple WeatherKit REST API client

=cut

our $VERSION = '0.12';

=head1 SYNOPSIS

    use Weather::WeatherKit;

    my $wk = Weather::WeatherKit->new(
        team_id    => $apple_team_id,          # Apple Developer Team Id
        service_id => $weatherkit_service_id,  # WeatherKit Service Id
        key_id     => $key_id,                 # WeatherKit developer key ID
        key        => $private_key             # Encrypted private key (PEM)
    );
    
    # Request current weather:
    my $report = $wk->get(
        lat      => $lat,      # Latitude
        lon      => $lon,      # Longitude
        dataSets => 'currentWeather'
    );

    # Request forecast for 8 days, use Weather::API::Base helper functions
    # for ISO dates, and get full HTTP::Response object to check for success
    use Weather::API::Base qw(:all);

    my $response = $wk->get_response(
        lat         => $lat,
        lon         => $lon,
        dataSets    => 'forecastHourly',
        hourlyStart => ts_to_iso_date(time()),
        hourlyEnd   => ts_to_iso_date(time()+8*24*3600)
    );

    if ($response->is_success) {
        my $json = $response->decoded_content;
    } else {
        die $response->status_line;
    }

=head1 DESCRIPTION

Weather::WeatherKit provides basic access to the Apple WeatherKit REST API (v1).
WeatherKit replaces the Dark Sky API and requires an Apple developer subscription.

Pease see the L<official API documentation|https://developer.apple.com/documentation/weatherkitrestapi>
for datasets and usage options as well as the L<required attribution|https://developer.apple.com/weatherkit/get-started/#attribution-requirements>.

It was made to serve the apps L<Xasteria|https://astro.ecuadors.net/xasteria/> and
L<Polar Scope Align|https://astro.ecuadors.net/polar-scope-align/>, but if your service
requires some extra functionality, feel free to contact the author about it.

=head1 CONSTRUCTOR

=head2 C<new>

    my $wk = Weather::WeatherKit->new(
        team_id    => "MLU84X58U4",
        service_id => "com.domain.myweatherapp",
        key_id     => $key_id,
        key        => $private_key?,
        key_file   => $private_key_pem?,
        language   => $lang_code?,
        timeout    => $timeout_sec?,
        expiration => $expire_secs?,
        ua         => $lwp_ua?,
        curl       => $use_curl?
    );
  
Required parameters:

=over 4

=item * C<team_id> : Your 10-character Apple developer Team Id - it can be located
on the Apple developer portal.

=item * C<service_id> : The WeatherKit Service Identifier created on the Apple
developer portal. Usually a reverse-domain type string is used for this.

=item * C<key_id> : The ID of the WeatherKit key created on the Apple developer portal.

=item * C<key_file> : The encrypted WeatherKit private key file that you created on
the Apple developer portal. On the portal you download a PKCS8 format file (.p8),
which you first need to convert to the PEM format. On a Mac you can convert it simply:

   openssl pkcs8 -nocrypt -in AuthKey_<key_id>.p8 -out AuthKey_<key_id>.pem

=item * C<key> : Instead of the C<.pem> file, you can pass its contents directly
as a string. If both are provided C<key> takes precedence over C<key_file>.

=back

Optional parameters:

=over 4

=item * C<language> : Language code. Default: C<en_US>.

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

=item * C<ua> : Pass your own L<LWP::UserAgent> to customise the agent string etc.

=item * C<curl> : If true, fall back to using the C<curl> command line program.
This is useful if you have issues adding http support to L<LWP::UserAgent>, which
is the default method for the WeatherKit requests. It assumes the C<curl> program
is installed in C<$PATH>.

=item * C<expiration> : Token expiration time in seconds. Tokens are cached until
there are less than 10 minutes left to expiration. Default: C<7200>.

=back

=head1 METHODS

=head2 C<get>

    my $report = $wk->get(
        lat      => $lat,
        lon      => $lon,
        dataSets => $datasets
        %args?
    );