currencylayer-historical-bank

A gem that calculates the exchange rate using published rates from currencylayer.com

Currencylayer API

{
  "timestamp": 1441101909,
  "source": "USD",
  "quotes": {
      /* 168 currencies */
      "USDAUD": 1.413637,
      "USDCAD": 1.316495,
      "USDCHF": 0.96355,
      "USDEUR": 0.888466,
      "USDBTC": 0.004322, /* Includes Bitcoin currency! */
      ...
      }
}

See more about Currencylayer product plans on https://currencylayer.com/product.

Installation

Add this line to your application's Gemfile:

gem 'currencylayer-historical-bank'

And then execute:

$ bundle

Or install it yourself as:

$ gem install currencylayer-historical-bank

Usage

# Minimal requirements
require 'money/bank/currencylayer_historical_bank'
mclb = Money::Bank::CurrencylayerHistoricalBank.new
mclb.access_key = 'your access_key from https://currencylayer.com/product'

# Update rates (get new rates from remote if expired or access rates from cache)
mclb.update_rates

# Force update rates from remote and store in cache
# mclb.update_rates(true)

# (optional)
# Set the base currency for all rates. By default, USD is used.
# CurrencylayerHistoricalBank only allows USD as base currency for the free plan users.
mclb.source = 'EUR'

# (optional)
# Set the seconds after than the current rates are automatically expired
# by default, they never expire, in this example 1 day.
mclb.ttl_in_seconds = 86400

# (optional)
# Use https to fetch rates from CurrencylayerHistoricalBank
# CurrencylayerHistoricalBank only allows http as connection for the free plan users.
mclb.secure_connection = true

# Define cache (string or pathname)
mclb.cache = 'path/to/file/cache'

# Set money default bank to currencylayer bank
Money.default_bank = mclb

More methods

mclb = Money::Bank::CurrencylayerHistoricalBank.new

# Returns the base currency set for all rates.
mclb.source

# Expires rates if the expiration time is reached.
mclb.expire_rates!

# Return true if the expiration time is reached.
mclb.expired?

# Get the API source url.
mclb.source_url

# Get the rates timestamp of the last API request.
mclb.rates_timestamp

How to exchange

# Exchange 1000 cents (10.0 USD) to EUR
Money.new(1000, 'USD').exchange_to('EUR')        # => #<Money fractional:89 currency:EUR>
Money.new(1000, 'USD').exchange_to('EUR').to_f   # => 8.9

# Format
Money.new(1000, 'USD').exchange_to('EUR').format # => €8.90

# Get the rate
Money.default_bank.get_rate('USD', 'CAD')        # => 0.9

See more on https://github.com/RubyMoney/money.

Using gem money-rails

You can also use it in Rails with the gem money-rails.

require 'money/bank/currencylayer_bank'

MoneyRails.configure do |config|
  mclb = Money::Bank::CurrencylayerHistoricalBank.new
  mclb.access_key = 'your access_key from https://currencylayer.com/product'
  mclb.update_rates

  config.default_bank = mclb
end

Cache

You can also provide a Proc as a cache to provide your own caching mechanism perhaps with Redis or just a thread safe Hash (global). For example:

mclb.cache = Proc.new do |v|
  key = 'money:currencylayer_bank'
  if v
    Thread.current[key] = v
  else
    Thread.current[key]
  end
end

Process

The gem fetches all rates in a cache with USD as base currency. It's possible to compute the rate between any of the currencies by calculating a pair rate using base USD rate.

Tests

You can place your own key on a file or environment variable named TEST_ACCESS_KEY and then run:

bundle exec rake

Refs

• Gem money
• Gem money-open-exchange-rates
• Gem money-historical-bank

Other Implementations

• Gem currencylayer
• Gem money-open-exchange-rates
• Gem money-historical-bank
• Gem eu_central_bank
• Gem nordea
• Gem google_currency

Contributing

• Fork it ( https://github.com/[your-username]/currencylayer-historical-bank/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

License

The MIT License

Copyright (c) 2017