view release on metacpan or  search on metacpan

lib/FixerIO/API.pm  view on Meta::CPAN

use 5.006;
use strict;
use warnings;
use HTTP::Tiny;
use JSON 'decode_json';
use Carp;

=head1 NAME

FixerIO::API - Access to the fixer.io currency exchange rate API.

=head1 VERSION

Version 0.1.0

=cut

our $VERSION = '0.1.0';


=head1 SYNOPSIS

    use FixerIO::API;

    my $access_key = <your-key-here>;
    my $fixer = FixerIO::API->new( $access_key );

    # get latest data
    my $ld = $fixer->latest;

    use DDP hash_max=>5;
    p $ld, as=>"Latest Data:";

    Will print,
    Latest Data:
    {
        success     1 (JSON::PP::Boolean),
        base        "EUR",
        date        "2023-09-03" (dualvar: 2023),
        timestamp   1693764783,
        rates       {
            AED   3.965325,
            AFN   79.575894,
            ALL   108.330797,
            AMD   418.325847,
            ANG   1.954454,
            (...skipping 165 keys...)
        }
    }

=head1 DESCRIPTION

This is a Perl module for accessing the API provided by fixer.io.  See, F<"http://fixer.io/documentation">.

This module doesn't export anything. Nor does it keep any data, other than your API access key. Your script will keep or do what it wants with the data.

You have to obtain your own API key from the fixer.io web site. There is a free option.

=head1 IMPLEMENTED ENDPOINTS

Please note that depending on your subscription plan, certain API endpoints may not be available.

=head2 LATEST RATES

Returns real-time exchange rate data for all available or a specific set of currencies.

Specifying symbols is not implemented. Changing the base is not implemented. The etags optimization is not implemented.

=head1 EXPORT

No exports.

=head1 SUBROUTINES/METHODS

=head2 new

Instantiate a new API access object. Pass in your API access key as an argument.

=cut

sub new {
    my $class = shift;
    my $access_key = shift;
    return undef unless defined $access_key;
    return bless \$access_key, $class;
}

=head2 api_call

Perform the HTTP(S) request, return the response data.

=cut

sub api_call {
    my ($self, $options, $defaults) = @_;
    my $ua = HTTP::Tiny->new(
	    agent => sprintf '%s/%s ', 'FixerIO-API', $VERSION
    );
    my %options = (
        %{$defaults},
        %{$options},
    );
    my $url = "http://data.fixer.io/api/latest?access_key=$$self";
    while (my ($k, $v) = each %options) {
        $url .= sprintf '&%s=%s', $k, $v; # values always have no spaces
    }
    my $resp = $ua->get($url);
    return $resp->{'content'} if $resp->{'success'};

    #TODO: Handle HTTP exceptions
    croak 'HTTP Error!? How can that be?';
}

=head2 latest

Return the latest data.

=cut

sub latest {
    my ($self, %options) = @_;