Package Exports

fixer-node

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (fixer-node) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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:

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

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!

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

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