NAME

    Net::Async::OpenExchRates - interact with OpenExchangeRates API
    <https://openexchangerates.org/> via IO::Async

SYNOPSIS

     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();

DESCRIPTION

    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
    <https://openexchangerates.org/> following its API docs
    <https://docs.openexchangerates.org> 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
    <https://metacpan.org/dist/Net-Async-OpenExchRates>

CONSTRUCTOR

 new

     $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
      <https://openexchangerates.org/account/app-ids>.

    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
      <https://docs.openexchangerates.org/reference/etags> 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
      <https://openexchangerates.org/signup> 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
      from usage.json API call, if the Last-Modified timestamp HTTP header
      that is attached with our existing response compared to current time
      is less than update_frequency then most probably even if we call the
      API it will return 304 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 as 0

    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.

METHODS

    All available methods are async/await following Future::AsyncAwait and
    Future

 do_request

       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.

 latest

       await $exch->latest();
       await $exch->latest('USD', 'CAD', ['JPY']);

    To request latest.json enpoint
    <https://docs.openexchangerates.org/reference/latest-json> 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.

 historical

       await $exch->historical($date, $base, @symbols);
       await $exch->historical('2024-04-04', 'CAD');

    To request historical/*.json endpoint
    <https://docs.openexchangerates.org/reference/historical-json> 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.

 currencies

       await $exch->currencies();
       # to list inactive currencies
       await $exch->currencies(0, 1);

    To request currencies.json endpoint
    <https://docs.openexchangerates.org/reference/currencies-json> from
    API. it mainly returns list of offered currencies by OpenExchangeRates
    API. takes two optional parameters:

    $show_alternative

      passed as 0 or 1, donating to include alternative currencies or not.

    $show_inactive

      passed as 0 or 1, donating to list inactive currencies or not.

 time_series

       await $exch->time_series($start, $end, $base, @symbols);
       await $exch->time_series('2024-04-02', '2024-04-04');

    To request time-series.json endpoint
    <https://docs.openexchangerates.org/reference/time-series-json> 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

 convert

       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
    <https://docs.openexchangerates.org/reference/convert> 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 to 1 when you want to make it to
      use $to for base to convert, and let it be as default: 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.

 ohlc

       await $exch->ohlc($date, $time, $period, $base, @symbols);
       await $exch->ohlc('2024-04-04', '02:00', '2m');

    To request ohlc.json endpoint
    <https://docs.openexchangerates.org/reference/ohlc-json> 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 or h: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.

 usage

       await $exch->usage();

    To request usage.json endpoint
    <https://docs.openexchangerates.org/reference/usage-json> from API.
    returning both subscription plan details and app_id API usage so far,
    along with current app status.

 app_plan

       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.

 app_usage

       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.

 app_features

       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

 app_status

       await $exch->app_status();

    Gets the current app_id status on the API, originally in "usage" call.

 plan_update_frequency

       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.

FIELD ACCESSORS

    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.

 last_http_response

       $exch->last_http_response();

    Used to access the complete HTTP::Response for the last request that
    has been made.

 app_id

       $exch->app_id();

    The current APP_ID that is registered with this instance.

 api_query_params

       $exch->api_query_params();

    Referenece of the list of parameters accepted by API.

 app_plan_keys

       $exch->app_plan_keys();

    To get list of subscription plan response hash keys from "usage" call.

 app_usage_keys

       $exch->app_usage_keys();

    To get list of current API usage response hash keys from "usage" call.

 app_features_keys

       $exch->app_features_keys();

    To get list of available API features.