Net::Async::OpenExchRates
- interact with OpenExchangeRates API via IO::Async
use Future::AsyncAwait;
use IO::Async::Loop;
use Net::Async::OpenExchRates;
my $loop = IO::Async::Loop->new();
my $exch = Net::Async::OpenExchRates->new(
app_id => 'APP_ID',
);
$loop->add( $exch );
my $latest = await $exch->latest();
This module is a simple IO::Async::Notifier wrapper class with a Net::Async::HTTP object constructed using Object::Pad. Made to communicate with OpenExchangeRates API providing all its available endpoints as methods to be called by a program.
Acting as an active Asynchronous API package for Open Exchange Rates
following its API docs along with providing extra functionalities
like pre-validation, local caching and respecting API update frequency depending on your APP_ID
subscription plan.
For examples and more ways to use this package, please check Examples directory in package distribution page
$exch = Net::Async::OpenExchRates->new( %args );
Returns a new Net::Async::OpenExchRates
instance,
which is a IO::Async::Notifier
too,
where one argument is required with others being optional, detailed as so:
-
app_id => STRING (REQUIRED)
The only required argument to be passed. Can be obtained from OpenExchangeRates Account page.
-
base_uri => STRING
default: 'https://openexchangerates.org'
The URL to be used as the base to form API request URI.
-
use_cache => BOOL
default: 1
Toggle to enable/disable the use of Cache::LRU to have the response locally available for repeated requests only if the API responded with
304 HTTP
code for a previously cached request. As OpenExchangeRates API offers Cache Control utilizing ETag identifiers. Having this enabled is effective for saving on network bandwidth and faster responses, but not much on API usage quota as it will still be counted as a resource request. -
cache_size => INT
default: 1024
The size limit for the Cache::LRU object. The maximum number of previous requests responses to be kept in memory.
-
respect_api_frequency => BOOL
default: 1
As every OpenExchangeRates API subscription plan comes with its own number of permitted requests per month and resources update frequency. This option is made purely to allow your program to query repeated requests without overwhelming API. If the request is already cached meaning we already have its response from a previous request invocation, it will check on the current resources
update_frequency
fromusage.json
API call, if theLast-Modified
timestamp HTTP header that is attached with our existing response compared to current time is less thanupdate_frequency
then most probably even if we call the API it will return304 HTTP
, hence in this case respect the API and instead of requesting it to confirm, return the response we already have without requesting again.Suitable for repeated requests, and using a restricted subscription plan.
-
enable_pre_validation => BOOL
default: 1
Mainly requested currencies, date/time values along with other limitations for some endpoints. These options are here to toggle whether to validate those parameters before requesting them or not.
-
local_conversion => BOOL
default: 1
Given that
convert
API endpoint is only available for Unlimited subscription plan, this option is to allow your program to perform conversion function locally, without applying any formatting to calculated amount. Not that if you want to use the API instead for "convert" method you need to pass this as0
-
keep_http_response => BOOL
default: 1
Used to allow your program to access the complete HTTP::Response from the last API request made through "last_http_response". If turned of by passing
0
last_http_response will stay empty.
All available methods are async/await
following Future::AsyncAwait and Future
await $exch->do_request($page, %args);
The generic method to perform HTTP request for any OpenExchangeRates API endpoint. It has the gist of the logic, from trying to check Cache if the request has been made before to actually triggering the request and parse its response. Takes to main arguments:
-
$page
as in the endpoint name that needs to be requested.
-
%args
A hash containing the named parameters to be passed as query parameters to the API call URI.
use only when you want parse the complete request yourself, you should be able to get all whats needed from API using other methods.
await $exch->latest();
await $exch->latest('USD', 'CAD', ['JPY']);
To request latest.json enpoint from API.
It accepts a list, ARRAYref
or a mixture of both for currencies as an argument where:
-
$base currency
as the first param where its
default: 'USD'
-
@symbols
the rest of the list as symbols to be filtered.
Note that show_alternative
is always passed as true
to the API.
await $exch->historical($date, $base, @symbols);
await $exch->historical('2024-04-04', 'CAD');
To request historical/*.json endpoint from API. Used to retrieve old rates, takes multiple parameters:
-
$date
required parameter; scalar string following a date format
YYYY-MM-DD
-
$base
base currency to be used with the request,
default: 'USD'
. -
@symbols
the rest of parameters will be taken the list of symbols to be filtered out. Can be passed as a flat list, an
ARRAYref
or mix of both.
note that show alternative is always on.
await $exch->currencies();
# to list inactive currencies
await $exch->currencies(0, 1);
To request currencies.json endpoint from API. it mainly returns list of offered currencies by OpenExchangeRates API. takes two optional parameters:
-
$show_alternative
passed as
0
or1
, donating to include alternative currencies or not. -
$show_inactive
passed as
0
or1
, donating to list inactive currencies or not.
await $exch->time_series($start, $end, $base, @symbols);
await $exch->time_series('2024-04-02', '2024-04-04');
To request time-series.json endpoint from API. Essentially its multiple historical requests just handled by OpenExchangeRates API itself. Takes a couple of parameters:
-
$start
Required start date of the period needed. Following
YYYY-MM-DD
format. -
$end
Required end date of the period needed. Following
YYYY-MM-DD
format. -
$base
Base currency for the prices requested.
default: 'USD'
-
@symbols
Symbols to be filtered out, can be passed as a flat list list or an
ARRAYref
await $exch->convert($value, $from, $to, $reverse_convert);
await $exch->convert(22, 'USD', 'CAD');
await $exch->convert(22, 'JPY', 'USD', 1);
To request convert endpoint from API. This endpoint is only available in Unlimited subscription plan, however you can enable "local_conversion" which will allow you to perform conversion operation locally, applying a simple math equation with no formatting to returned value so make sure to apply your own decimal point limit to returned value. Accepts these parameters:
-
$value
The amount you'd like to be converted. keep in mind that OpenExchangeRates API only accepts
INT
values. However enabling "local_conversion" will accept none integer values too and be able to convert it. -
$from
The currency of the
$value
passed above, passed as three characters. -
$to
The currency to be converted to.
-
$reverse_convert
This is used when "local_conversion" is enabled, in order to overcome another restriction on API. Which is to get the prices of base currencies other than
USD
. Set it to1
when you want to make it to use$to
for base to convert, and let it be asdefault: 0
to use$from
currency as the base to convert.
In order for "local_conversion" to work properly with Free subscription plans, one of the currencies has to be USD
where you'd set "$reverse_convert" to 1
when you are converting $to
USD
rather than $from
.
await $exch->ohlc($date, $time, $period, $base, @symbols);
await $exch->ohlc('2024-04-04', '02:00', '2m');
To request ohlc.json endpoint from API. Retrieving OHLC data requires some parameters to be present which are:
-
$date
Date for selection timeframe needed, follows
YYYY-MM-DD
format. -
$time
Time for selection timeframe needed, follows
hh:mm
orh:m
. All timings would be based on UTC, as thats what API supports. -
$period
Period of OHLC needed, like:
'1m'
,'12h
,'1d'
, and so on. -
$base
Optional base currency,
default: 'USD'
-
@symbols
Optional list of symbols to filter result based on.
await $exch->usage();
To request usage.json endpoint from API. returning both subscription plan details and app_id API usage so far, along with current app status.
await $exch->app_plan();
await $exch->app_plan($key);
Retrieves only the subscription plan details from "usage" call, with the possibility of passing:
-
$key
to get a specific key value from subscription plan details.
await $exch->app_usage();
await $exch->app_usage($key);
Retrieves only the application current API usage section from "usage" method.
-
$key
A specific key to get value for from API usage.
await $exch->app_features();
await $exch->app_features($key);
Retrieves the features that are currently enabled for current app_id
, accepts:
-
$key
as a specific feature, in order to know whether its enabled or not by API
await $exch->app_status();
Gets the current app_id
status on the API, originally in "usage" call.
await $open_exch_api->plan_update_frequency();
used in order to specifically retrieve the subscription plan update_frequency in seconds. Which is the rate that data are refreshed on current active plan.
No real difference between the other typical methods except that they are not async/await. Also for most of them they will only be populated after the first request.
$exch->last_http_response();
Used to access the complete HTTP::Response for the last request that has been made.
$exch->app_id();
The current APP_ID
that is registered with this instance.
$exch->api_query_params();
Referenece of the list of parameters accepted by API.
$exch->app_plan_keys();
To get list of subscription plan response hash keys from "usage" call.
$exch->app_usage_keys();
To get list of current API usage response hash keys from "usage" call.
$exch->app_features_keys();
To get list of available API features.