A Node.js SDK to interact with the fixer.io API for currency conversion and exchange rates.
For release notes, see the CHANGELOG.
The Future Studio University supports development of this Node.js library 🚀
Join the Future Studio University and Skyrocket in Node.js
Node.js v8 (or newer)
fixer-node uses async/await which requires Node.js v8 or newer.
Add fixer-node as a dependency to your project:
# NPM v5 users, this way is yours
npm i fixer-node
# you’re using NPM v4:
npm i -S fixer-nodeInitialize an instance of fixer-node and pass your fixer.io access key as an argument:
const Fixer = require('fixer-node')
const fixer = new Fixer('access-key')The constructor of fixer-node requires an access key as the first argument.
The second argument is an options object allowing the following properties:
https:(boolean) set the fixer.io API base URL to eitherhttpsorhttp; default:http
const Fixer = require('fixer-node')
const fixer = new Fixer('access-key', {
https: true
})fixer-node throws a custom error instance: FixerError.
The FixerError contains the fixer.io API related error properties for info, code, and type.
The error message is derived from the info property.
const Fixer = require('node-fixer')
const fixer = new Fixer('access-key')
try {
const data = fixer.base({ base: 'USD' })
} catch (err) {
// err.info is the same as err.message,
// e.g. "Your monthly API request volume has been reached. Please upgrade your plan"
const info = err.info
// err.code the fixer.io API code,
// e.g. "201" which represents "An invalid base currency has been entered."
const code = err.code
}Find more details on errors in the fixer.io API docs.
aka “how to use this library”
fixer-node supports all fixer.io API endpoints. Here’s an overview on how to use the methods.
Request a list of currency symbols. This is a mapping between the currency shortcut (EUR) and full name (Euro).
const data = await fixer.symbols()Request the latest exchange rates.
The .latest() method accepts two parameters:
symbols: (string) a list of symbols you want the exchange rates for (this reduces the response payload)base: (string) the base currency
// get the latest rates for all currencies
const latest = await fixer.latest()
// get the latest rates for selected currencies
const latest = await fixer.latest({ symbols: 'EUR, USD, AUD' })
// get the latest rates for selected currencies and base
const latest = await fixer.latest({ symbols: 'EUR, USD', base: 'AUD' })Request exchange rates for a given base.
// get all rates for a selected base
const base = await fixer.base({ base: 'AUD' })
// get specific rates for a selected base
const base = await fixer.base({ base: 'AUD', symbols: 'USD, EUR' })Request historic exchange rates for a given day.
// get exchange rates for May 9th, 2018
const date = await fixer.forDate({ date: '2018-05-09' })
// with symbols
const date = await fixer.forDate({ date: '2018-05-09', symbols: 'USD, EUR, AUD' })
// with symbols and base
const date = await fixer.forDate({ date: '2018-05-09', symbols: 'EUR, AUD', base: 'USD' })Convert an amount from one currency to another.
The .convert() method is aliased as fromTo().
Use both, .convert() and .fromTo(), for the same operation.
// 25 from GBP to JPY
const convert = await fixer.convert({ from: 'GBP', to: 'JPY', amount: 25 })
// 25 from GBP to JPY on 2018-05-08
const convert = await fixer.fromTo({ from: 'GBP', to: 'JPY', amount: 25, date: '2018-05-08' })Historical exchange rates between two dates.
The .timeseries() method is aliased as between().
Use both, .timeseries() and .between(), for the same operation.
// start - end
const timeseries = await fixer.timeseries({
start_date: '2018-05-05',
end_date: '2018-05-08'
})
// start - end with base and symbols
const timeseries = await fixer.between({
start_date: '2018-05-05',
end_date: '2018-05-08',
symbols: 'EUR, USD',
base: 'AUD'
})Retrieve information about how currencies fluctuate on a day-to-day basis.
// start - end
const fluctuation = await fixer.fluctuation({
start_date: '2018-05-05',
end_date: '2018-05-08'
})
// start - end with base and symbols
const fluctuation = await fixer.fluctuation({
start_date: '2018-05-05',
end_date: '2018-05-08',
symbols: 'EUR, USD',
base: 'AUD'
})Do you miss a feature? Please don’t hesitate to create an issue with a short description of your desired addition to this plugin.
- fixer.io: exchange rate and currency conversion
We highly appreciate your pull request and any kind of support!
- Create a fork
- Create your feature branch:
git checkout -b my-feature - Commit your changes:
git commit -am 'Add some feature' - Push to the branch:
git push origin my-new-feature - Submit a pull request 🚀
MIT © Future Studio
futurestud.io · GitHub @futurestudio · Twitter @futurestud_io