fixer-node

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 = require('fixer-node')
const fixer = new 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 either https or http; default: http

const Fixer = require('fixer-node')
const fixer = new 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 = 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.

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.symbols()

Latest

Request the latest exchange rates.

The .latest() method accepts two parameters:

1. symbols: (string) a list of symbols you want the exchange rates for (this reduces the response payload)
2. 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' })

Base

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' })

Historic

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

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' })

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 - 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'
})

Fluctuation

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'
})

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!

1. Create a fork
2. Create your feature branch: git checkout -b my-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request 🚀

License

MIT © Future Studio

---

futurestud.io  ·  GitHub @fs-opensource  ·  Twitter @futurestud_io

Changelog

2.0.0 - 2018-05-16

The breaking change from 1.0 to 2.0 is that all methods accept an object as parameter instead of individual parameters. This allows you to pass the parameters of interest.

Example:

// request latest rates for a given base rate

// before:
// the first param is "symbols", but we don't necessarily want to specify it
const latest = fixer.latest(undefined, 'USD')

// now:
// add "symbols: 'EUR, AUD'" if you wish, but not necessary
const latest = fixer.latest({ base: 'USD' })

Added

• 2.0.0 release 🚀 🎉
• .between() and .historical() methods to access historic rates (.between() and .historial() are aliased and run the same functionality)
• .fromTo() and .convert() methods to convert between rates (.fromTo() and .convert() are aliased and run the same functionality)
• .timeseries() method to access exchange rates for a time range
• .fluctuation() method to access exchange rate changes for a selected time range
• code snippets for new methods in Readme
• all methods accept an options object
• tests for new methods

Updated

• code examples in Readme for existing methods from 1.0