https://github.com/matthutchinson/ecb_exchange
ECB Exchange 💷 💵 💴 💶
https://github.com/matthutchinson/ecb_exchange
currency currency-converter currency-exchange-rates ecb ecb-rates exchange exchange-rate money
Last synced: about 1 year ago
JSON representation
ECB Exchange 💷 💵 💴 💶
- Host: GitHub
- URL: https://github.com/matthutchinson/ecb_exchange
- Owner: matthutchinson
- License: lgpl-3.0
- Created: 2016-09-21T15:36:07.000Z (almost 10 years ago)
- Default Branch: main
- Last Pushed: 2021-02-09T10:03:06.000Z (over 5 years ago)
- Last Synced: 2025-03-25T08:11:14.467Z (over 1 year ago)
- Topics: currency, currency-converter, currency-exchange-rates, ecb, ecb-rates, exchange, exchange-rate, money
- Language: Ruby
- Homepage:
- Size: 81.1 KB
- Stars: 2
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# ECB Exchange
[](http://rubygems.org/gems/ecb_exchange)
[](https://travis-ci.com/matthutchinson/ecb_exchange)
[](https://depfu.com/github/matthutchinson/ecb_exchange)
[](https://codeclimate.com/github/matthutchinson/ecb_exchange/maintainability)
[](https://codeclimate.com/github/matthutchinson/ecb_exchange/test_coverage)
Currency conversion using the European Central Bank's foreign [exchange
rates](https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml). Rates
for the last 90 days are fetched and cached on demand. All calculations are
performed and returned as `BigDecimal` (usually a [good
idea](https://makandracards.com/makandra/1178-bigdecimal-arithmetic-in-ruby)
when dealing with money).
## Requirements
* [Ruby](http://ruby-lang.org/) >= 2.3
## Installation
Add this line to your Gemfile and run `bundle install`:
```ruby
gem 'ecb_exchange'
```
## Usage
Convert an amount from one currency to another:
```ruby
ECB::Exchange.convert(100, from: 'EUR', to: 'GBP')
=> 0.88235e2
```
The converted amount (using today's current rate) will be returned as
`BigDecimal`. In doing this, the gem will fetch and cache ECB rates for the last
90 days.
Convert an amount on a specific date:
```ruby
ECB::Exchange.convert(100, from: 'EUR', to: 'GBP', date: Date.parse('2017-01-11'))
=> 0.87235e2
```
To fetch the exchange rate multiplier between two currencies:
```ruby
ECB::Exchange.rate(from: 'EUR', to: 'USD') # pass an optional `date` arg here too
=> 0.11969e1
```
You can ask for an array of all supported currencies with:
```ruby
ECB::Exchange.currencies
=> ["USD", "JPY", "BGN", "CZK", "DKK", "GBP", "HUF" ... ]
```
Finally, you can adjust the rates endpoint by setting your own
`XMLFeed.endpoint` (e.g. in an initializer):
```ruby
ECB::Exchange::XMLFeed.endpoint = "http://my-awesome-service.com/feed.xml"
```
The XML feed at this endpoint must conform to the [ECB
rates](https://www.ecb.europa.eu/stats/eurofxref/eurofxref-hist-90d.xml)
structure.
## Handling Errors
Not all dates, rates or currencies may be available, or the remote endpoint
could be unresponsive. For these cases consider handling these errors:
* `ECB::Exchange::DateNotFoundError`
* `ECB::Exchange::CurrencyNotFoundError`
* `ECB::Exchange::ResponseError`
* `ECB::Exchange::ParseError`
Or rescue `ECB::Exchange::Error` to catch any of them.
## Caching
By default rates will be cached to one of the following backend stores (in this
order of preference).
* Your own backend cache store (see below)
* `Rails.cache`
* An `ECB::Exchange::MemoryCache` instance (a simple in memory cache store)
To configure your own backend store (e.g. in an initializer):
```ruby
ECB::Exchange::Cache.backend = MyAwesomeCache.new
# this cache must implement public `read(key)` and `write(key, value)` methods
```
All keys in the cache are name-spaced with a `ecb_exchange_rates_for_date-`
prefix.
## Development
Check out this repo and run `bin/setup`, this will install gem dependencies and
generate docs. Use `bundle exec rake` to run tests and generate a coverage
report.
You can also run `bin/console` for an interactive prompt to experiment with the
code.
## Tests
MiniTest is used for testing. Run the test suite with:
$ rake test
## Docs
Generate docs for this gem with:
$ rake rdoc
## Troubles?
If you think something is broken or missing, please raise a new
[issue](https://github.com/matthutchinson/ecb_exchange/issues). Please remember
to check it hasn't already been raised.
## Contributing
Bug [reports](https://github.com/matthutchinson/ecb_exchange/issues) and [pull
requests](https://github.com/matthutchinson/ecb_exchange/pulls) are welcome on
GitHub. When submitting pull requests, remember to add tests covering any new
behaviour, and ensure all tests are passing on
[Travis](https://travis-ci.com/matthutchinson/ecb_exchange). Read the
[contributing
guidelines](https://github.com/matthutchinson/ecb_exchange/blob/master/CONTRIBUTING.md)
for more details.
This project is intended to be a safe, welcoming space for collaboration, and
contributors are expected to adhere to the [Contributor
Covenant](http://contributor-covenant.org) code of conduct. See
[here](https://github.com/matthutchinson/ecb_exchange/blob/master/CODE_OF_CONDUCT.md)
for more details.
## Todo
* Better RDoc documentation.
* A Rails app to demo this gem (e.g. with a one-click Heroku install).
## License
The code is available as open source under the terms of
[LGPL-3](https://opensource.org/licenses/LGPL-3.0).
## Links
* [Gem](http://rubygems.org/gems/ecb_exchange)
* [Travis CI](https://travis-ci.com/matthutchinson/ecb_exchange)
* [Maintainability](https://codeclimate.com/github/matthutchinson/ecb_exchange/maintainability)
* [Test Coverage](https://codeclimate.com/github/matthutchinson/ecb_exchange/test_coverage)
* [RDoc](http://rdoc.info/projects/matthutchinson/ecb_exchange)
* [Issues](http://github.com/matthutchinson/ecb_exchange/issues)
* [Report a bug](http://github.com/matthutchinson/ecb_exchange/issues/new)
* [GitHub](https://github.com/matthutchinson/ecb_exchange)