module OXR

All use of OXR takes place through module methods.

Before you can make API calls, you must configure OXR with your Open Exchange Rates App ID. Visit openexchangerates.org to sign up and generate one.

OXR.configure do |config|
  config.app_id = 'XXXX'
end

Optionally you may also specify the base currency for the conversion rates. The default base currency is USD.

OXR.configure do |config|
  config.app_id = 'XXXX'
  config.base = 'JPY'
end

If you will be using OXR in a test environment, you may want to test the substitute local files for the API endpoints to provide deterministic results and avoid running over your Open Exchange Rates API request quota.

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

  def teardown
    OXR.reset_sources
  end
end

To quickly get an exchange rate from the base currency to a given currency, use `OXR.get_rate`.

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

This method is aliased as `OXR.[]`.

OXR['GBP'] # => 0.703087

Pass the `:on` keyword argument to get an historical exchange rate on a given date.

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

Constants

VERSION

Public Class Methods

[](code, on: nil)

Alias for: get_rate

configuration() click to toggle source

Returns the OXR configuration struct.

# File lib/oxr.rb, line 160
def configuration
  @configuration ||= Configuration.new
end

configure() { |configuration| ... } click to toggle source

Returns the OXR configuration struct.

If given a block, the configuration will be yielded to the block.

# File lib/oxr.rb, line 153
def configure
  yield configuration if block_given?
  configuration
end

currencies() click to toggle source

Returns a Hash mapping currency codes to full currency names.

# File lib/oxr.rb, line 115
def currencies
  call configuration.currencies
end

get_rate(code, on: nil) click to toggle source

Get the latest exchange rate for currency identified by code.

If the optional on keyword is provided, it instead returns the historical exchange rate on the given date.

# File lib/oxr.rb, line 102
def get_rate(code, on: nil)
  data = if on
           historical on: on
         else
           latest
         end
  data['rates'][code.to_s]
end

Also aliased as: []

historical(on:) click to toggle source

Returns a Hash mapping currency codes to their historical exchange rate on the date given by the on keyword argument.

The exchange rate is relative to the configured base currency.

# File lib/oxr.rb, line 124
def historical(on:)
  call configuration.historical on
end

latest() click to toggle source

Returns a Hash mapping currency codes to their latest exchange rate.

The exchange rate is relative to the configured base currency.

# File lib/oxr.rb, line 132
def latest
  call configuration.latest
end

new(app_id) click to toggle source

DEPRECATED: TO BE REMOVED IN 0.7.

OXR should no longer be instantiated explicitly.

Call OXR.configure to specify the application ID and use the module methods below to access the different API endpoints.

# File lib/oxr.rb, line 88
def new(app_id)
  warn '[DEPRECATION] OXR.new is deprecated and will be removed from 0.7.' \
    " Use OXR class methods instead (from #{caller(1..1).first})."
  configure do |config|
    config.app_id = app_id
  end
  self
end

reset_sources() click to toggle source

Resets API endpoints to their defaults.

# File lib/oxr.rb, line 145
def reset_sources
  configure(&:reset_sources)
end

usage() click to toggle source

Returns a Hash containinng details about the Open Exchange Rates account and current usage statistics.

# File lib/oxr.rb, line 139
def usage
  call configuration.usage
end

Private Class Methods

call(endpoint) click to toggle source

# File lib/oxr.rb, line 166
def call(endpoint)
  # This method makes it possible for a user to provide an endpoint path as
  # either a String, Pathname, or URI. We will massage it until we have
  # something that responds to #read.
  endpoint = URI.parse(endpoint.to_s) unless endpoint.respond_to?(:read)
  endpoint = File.open(endpoint.path) unless endpoint.respond_to?(:read)

  JSON.parse endpoint.read
rescue OpenURI::HTTPError => e
  raise ApiError, e
end