This gem provides a basic interface to the Open Exchange Rates API. At present, only the API calls available to free plans have been implemented.

Add this line to your application's Gemfile:

gem 'oxr'

And then execute:

$ bundle

Or install it yourself as:

$ gem install oxr

If you have not done so already, sign up for account on Open Exchange Rates. Once you have an account, go to Your Dashboard and locate your App ID.

Configure OXR with your App ID by calling OXR.configure:

OXR.configure do |config|
  config.app_id = 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
  # config.base = 'USD'
end

(If you are using OXR within a Rails application, you will probably want to put this in an initializer.)

You can get current exchange rates using OXR.get_rate:

OXR.get_rate 'GBP' # => 0.703087
OXR.get_rate 'JPY' # => 111.7062

You can also use the OXR.[] shortcut method.

OXR['GBP'] # => 0.703087

OXR.get_rate accepts an optional keyword argument to retrieve historical exchange rates for given dates. The provided date should be an object which responds to #strftime.

OXR.get_rate 'GBP', on: Date.new(2015, 6, 14) # => 0.642607

You perform more complex operations by using the lower-level API calls. These methods return the raw JSON responses returned by Open Exchange Rates (parsed using the json gem).

Get the latest exchange rates with OXR.latest.

OXR.latest

This will return a JSON object with a structure similar to the following:

{
 "disclaimer"=>"Usage subject to terms: https://openexchangerates.org/terms",
 "license"=>"https://openexchangerates.org/license",
 "timestamp"=>1512842416,
 "base"=>"USD",
 "rates"=>
  {
    "AED"=>3.673097,
    "AFN"=>68.693,
    "ALL"=>113.595865,
    # ...
    "ZAR"=>13.65526, 
    "ZMW"=>10.243477,
    "ZWL"=>322.355011
  }
}

Get historical exchange rates for specific dates with OXR.historical. This method requires you to provide the date you wish to lookup. The date argument should respond to #strftime.

OXR.historical on: Date.new(2016, 3, 24)

This will return a JSON object with a structure similar to that returned by OXR.latest.

Get a list of available currencies with OXR.currencies.

OXR.currencies

Get information about your account including your usage for the current period with OXR.usage.

OXR.usage

Normally, any API call will send a request to Open Exchange Rates. Since your plan allows a limited number of requests per month, you probably want to avoid this when running in a test environment. You can stub the responses of specific API calls by configuring the endpoint for specific calls to use a local file instead of an HTTP request. Just provide a JSON file that reflects the payload of an actual API call. You may provide this as a Pathname or a URI object, but a plain old String will work as well. (You will find usable JSON files in test/fixtures included with this gem.)

When you're done, you can call OXR.reset_sources to restore the default behavior.

Below is an example of configuring OXR within a test.

class SomeTest < Minitest::Test
  def setup
    OXR.configure do |config|
      config.latest = 'test/fixtures/sample.json'
    end
  end

  def teardown
    OXR.reset_sources
  end
end

(You might consider doing this in your development environment as well.)

The interface has changed between the 0.2.0 and 0.3.0 tags. It is no longer necessary to instantiate an OXR object. The API calls are available as class methods directly on the OXR module.

# Before
oxr = OXR.new 'YOUR_APP_ID'
oxr['JPY']
oxr.usage

# Now
OXR.configure do |config|
  config.app_id = 'YOUR_APP_ID'
end
OXR['JPY']
OXR.usage

(You can still call OXR.new, but this behavior will generate a deprecation warning.)

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/jparker/oxr.

The gem is available as open source under the terms of the MIT License.