Module: OXR

Defined in:
lib/oxr.rb,
lib/oxr/version.rb,
lib/oxr/configuration.rb

Overview

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

Defined Under Namespace

Classes: ApiError, Configuration, Error

Constant Summary collapse

VERSION = 
'0.6.1'

Class Method Summary collapse

Class Method Details

.configuration ⇒ Object

Returns the OXR configuration struct.



160
161
162
 
# File 'lib/oxr.rb', line 160

def configuration
  @configuration ||= Configuration.new
end

.configure {|configuration| ... } ⇒ Object

Returns the OXR configuration struct.

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

Yields:



153
154
155
156
 
# File 'lib/oxr.rb', line 153

def configure
  yield configuration if block_given?
  configuration
end

.currencies ⇒ Object

Returns a Hash mapping currency codes to full currency names.



115
116
117
 
# File 'lib/oxr.rb', line 115

def currencies
  call configuration.currencies
end

.get_rate(code, on: nil) ⇒ Object Also known as: []

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.



102
103
104
105
106
107
108
109
 
# 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

.historical(on:) ⇒ Object

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.



124
125
126
 
# File 'lib/oxr.rb', line 124

def historical(on:)
  call configuration.historical on
end

.latest ⇒ Object

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

The exchange rate is relative to the configured base currency.



132
133
134
 
# File 'lib/oxr.rb', line 132

def latest
  call configuration.latest
end

.new(app_id) ⇒ Object

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.



88
89
90
91
92
93
94
95
 
# 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 ⇒ Object

Resets API endpoints to their defaults.



145
146
147
 
# File 'lib/oxr.rb', line 145

def reset_sources
  configure(&:reset_sources)
end

.usage ⇒ Object

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



139
140
141
 
# File 'lib/oxr.rb', line 139

def usage
  call configuration.usage
end