fixer-node
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
Requirements
Node.js v8 (or newer)
fixer-node
uses async/await which requires Node.js v8 or newer.
Installation
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-node
Usage
Initialize an instance of fixer-node
and pass your fixer.io access key as an argument:
const Fixer = const fixer = 'access-key'
Options
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 eitherhttps
orhttp
; default:http
const Fixer = const fixer = 'access-key' https: true
Error Handling
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 = const fixer = 'access-key' try const data = fixer 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 = errinfo // err.code the fixer.io API code, // e.g. "201" which represents "An invalid base currency has been entered." const code = errcode
Find more details on errors in the fixer.io API docs.
API
aka “how to use this library”
fixer-node
supports all fixer.io API endpoints. Here’s an overview on how to use the methods.
Symbols
Request a list of currency symbols. This is a mapping between the currency shortcut (EUR) and full name (Euro).
const data = await fixer
Latest
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 currenciesconst latest = await fixer // get the latest rates for selected currenciesconst latest = await fixer // get the latest rates for selected currencies and baseconst latest = await fixer
Base
Request exchange rates for a given base.
// get all rates for a selected baseconst base = await fixer // get specific rates for a selected baseconst base = await fixer
Historic
Request historic exchange rates for a given day.
// get exchange rates for May 9th, 2018const date = await fixer // with symbolsconst date = await fixer // with symbols and baseconst date = await fixer
Convert
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 JPYconst convert = await fixer // 25 from GBP to JPY on 2018-05-08const convert = await fixer
Time-Series
Historical exchange rates between two dates.
The .timeseries()
method is aliased as between()
.
Use both, .timeseries()
and .between()
, for the same operation.
// start - endconst timeseries = await fixer // start - end with base and symbolsconst timeseries = await fixer
Fluctuation
Retrieve information about how currencies fluctuate on a day-to-day basis.
// start - endconst fluctuation = await fixer // start - end with base and symbolsconst fluctuation = await fixer
Feature Requests
Do you miss a feature? Please don’t hesitate to create an issue with a short description of your desired addition to this plugin.
Links & Resources
- fixer.io: exchange rate and currency conversion
Contributing
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 🚀
License
MIT © Future Studio
futurestud.io · GitHub @fs-opensource · Twitter @futurestud_io