CcyConvertor

CcyConvertor provides live currency rate for various currencies and allows to convert money from one currency to other. Currently it supports 3 rate provider. New rate provider can be easily plugged in

Installation

Add this line to your application's Gemfile:

gem 'ccy_convertor'

And then execute:

$ bundle

Or install it yourself as:

$ gem install ccy_convertor

Usage

Once gem is installed you can find out exchange rate between currency as follows

CcyConvertor.rate(from_ccy: 'USD', to_ccy: 'NZD') # will use default rate provider to get rate

Note: Default rate provider is CcyConvertor::YahooFinance. You can change default rate provider. Check configuration section

Rate provider can also be provided as a parameter. Rate provider is a class which provides rate by using rest_api

CcyConvertor.rate(from_ccy: 'USD', to_ccy: 'NZD', rate_provider: CcyConvertor::OpenExchangeRate)
CcyConvertor.rate(from_ccy: 'USD', to_ccy: 'NZD', rate_provider: CcyConvertor::CurrencyLayer)

You can also directly use rate provider class as follows.

CcyConvertor::OpenExchangeRate.rate('USD', 'INR') # will return USD/INR rate

Note: CcyConvertor::OpenExchangeRate and CcyConvertor::CurrencyLayer requires api_key. You can register at respective websites to get a api key

Rate Providers

Rate provider class name	rest api source	Api key required
CcyConvertor::YahooFinance	'yahoo.finance.xchange' table yql	no
CcyConvertor::OpenExchangeRate	www.openexchangerates.org	yes
CcyConvertor::CurrencyLayer	www.currencylayer.com	yes

Api key can be provided individually to this classes as

CcyConvertor::OpenExchangeRate.api_key = 'XXXXXXXXX'
CcyConvertor::OpenExchangeRate.api_key = 'XXXXXXXXX'

Also check configuration section to know other ways to provide api_key to rate provider classes

You can convert money from one currency to another in following ways Below code will use rate provided from www.openexchangerates.org

CcyConvertor::OpenExchangeRate.convert(from_ccy: 'USD', to_ccy: 'NZD', amount: 10)

Below code will use default rate provider. Default rate provider is configurable . Check configuration section

CcyConvertor.convert(from_ccy: 'USD', to_ccy: 'NZD', amount: 10)

You can also get all currency rate (rate matrix) with respect to USD in single request for OpenExchangeRate and CurrencyLayer rate provider

Ccyconvertor::OpenExchangeRate.rate_matrix
Ccyconvertor::CurrencyLayer.rate_matrix

Above method will return hash with currency code as key and rate as value. All rates would be with respect to USD. OpenExchangeRate do not allow us to specify other base currency and USD is always the base currency.

While For Ccyconvertor::CurrencyLayer we can specify the base currency

Ccyconvertor::CurrencyLayer.rate_matrix('NZD')

All rates returned would be with respect to NZD. If no parameter is given then base currency is USD by default

Note: You cannot provide base currency for free account at currencylayer.com. By defualt base currency will be USD. You need a paid account at currencylayer.com to supply base currency. And Ccyconvertor::YahooFinance do not support rate_matrix method

Configuration

You can configure following parameters

default_rate-provider: Default rate provider is the rate provider which is used when no rate provider is species. Rate provider is a api service that this gem uses to provide rate. By default default rate provider is CcyConvertor::YahooFinance. Check rate providers details here
api_keys: CcyConvertor::OpenExchangeRate and CcyConvertor::CurrencyLayer provider requires api_key. You can register at there respective sites to get the api_key
cache_duration: specifies the time for which the response would be cached. By default this time is zero seconds i.e no caching is done by default. If cache_duration is 60 seconds and if you want a exchange rate of USD/INR multiple times in your application, request to rate provider would be made only once in 60 seconds and after 60 seconds next request would be made. ActiveSupport::Cache is used for caching
roud_up_rate: This takes fixnum which tells number of decimal places to which the rate would be rounded to.
roud_up_amount: This takes fixnum which tells number of decimal places to which the rate would be rounded to.

Sample configuration:

CcyConvertor.configure do |config|
  config.round_up_rate = 4
  config.round_up_amount = 4
  config.default_rate_provider = CcyConvertor::CurrencyLayer
  config.api_keys = {
    open_exchange_rate: 'XXXXXXXXX',
    currency_layer: 'XXXXXX'
  }
  config.cache_duration = {
    open_exchange_rate: 20,
    yahoo_finance: 30,
    currency_layer: 20
  }
end

If you are using rails, above code can be pasted in config/initializers/ccy_convertor.rb

Note: api_keys and cache_duration expects hash. Hash key is name of the class without module name in a underscore format

Adding new rate provider

Its simple to add a new rate provider. You can plug in any rate provider which provides rest api.

Steps for adding rate provider that support api call to get all rate in single api call:

Make a class with appropriate name inherit it from CccyConvertor::RateProvider
Add following class methods

  rest_url_for_rate_matrix(base_ccy=nil)

Above method should return rest api url to get rates of alll currencies.

rate_matrix(base_ccy=nil)

Above method should return rates in hash format as

{
    'currency_code1' => rate with respect to base_ccy,
    'currency_code2' => rate with respect to base_ccy
}

Note: currency_code should be in upper case You can call rate_matrix_response(base_ccy) method inside rate_matrix(base_ccy) method to get response from url returned by rest_url_for_rate_matrix(base_ccy=nil) method Once you get response from rate_matrix_response method you can convert it to response format as mentioned above

Steps for adding rate provider that does not support api call to get all rate in single api call:

Make a class with appropriate name inherit it from CccyConvertor::RateProvider
Add following class methods

rest_url_for_rate(from_ccy, to_ccy)

Above method should return url for geting exchange rate between from_ccy and to_ccy

rate(from_ccy, to_ccy)

Above method should return exchange rate(Numeric type) between from_ccy and to_ccy. You can call rate_response(from_ccy, to_ccy) inside rate(from_ccy, to_ccy) to get response from url returned by rest_url_for_rate(from_ccy, to_ccy)

Now you can directly use new rate provider added by you as an existing rate provider present in the gem. You can also use all the cofiguration present for th rate provider. If rate provider added by you require api_key, you can provide it as metioned in configurtion section. If you want to use api_key inside you rate provider class, you can use class method api_key to access it. Check rate providers inside lib/rate_providers for more information

Contributing

Fork it ( https://github.com/rohanpujaris/ccy_convertor/fork )
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
Create a new Pull Request

rohanpujaris / ccy_convertor