@apilayer/fixer v0.1.6

fixer-js

Fixer is a simple and lightweight API for current and historical foreign exchange (forex) rates.

Installation

Using npm

npm install --save @apilayer/fixer

or yarn

yarn add @apilayer/fixer

Getting Started

Head over to Fixer and create an account. Copy access key from dashboard.

import Fixer from '@apilayer/fixer';

const layer = new Fixer({
  key: "<your-access-key>"
  base: "USD",
  secure: false
})

Alternatively, you can change the default currency used by the library by:

layer.setBase("GBP")

Unsupported currency codes with throw an error.

If you're using typescript, you can import BaseType type.

import Fixer, { BaseType } from '@apilayer/fixer';

const layer = new Fixer({
  ...
  base: BaseType.USD,
})

Note:

RequestDate type represents a string matching "YYYY-mm-dd" or a date object

Latest rates

To fetch current live rates, use the latest() method and pass in string slice of accepted currencies.

Signature:

latest(symbols: BaseType[]): Promise<Latest>

Example:

const response = layer.latest(["GBP", "NGN"])

console.log("response:", response)

Response:

{
	success: true,
	timestamp: 1566902074,
	base: "USD",
	rates: {
    "USDGBP": "0.82",
    "USDNGN": "366.02",
  }
}

An unsupported currency code will cause an error.

Historical

To get rates for a currency pair at a date in the past, you should make a historical request:

Signature:

historical(date: RequestDate, symbols: BaseType[]): Promise<Historical>

Example:

const response = layer.historical("2019-01-21", ["GBP", "NGN"])

console.log("response:", response)

Response:

{
  success: true,
	historical: true,
	timestamp: 1566902074,
  base: "USD",
  date: "2019-06-01",
	rates: {
    "USDGBP": "0.82",
    "USDNGN": "366.02",
  }
}

Auto Conversion

It is also possible to convert an amount from a currency to its equivalent value in another currency.

Signature:

convert(
  from: string,
  to: string,
  amount: number,
  date: RequestDate = null
): Promise<Convert>

Example:

const response = layer.convert("USD", "GBP", 100.00)

console.log("response:", response)

The above call does a conversion of 100 USD to GBP as at the current date.

Response:

{
  success: true,
	info: {
    timestamp: 1566902074,
    rate: 82.00,
  },
  result: 82.00,
	query: {
    from: "USD",
    to: "GBP",
    amount: 100.00,
  },
	historical: false,
  date: "2019-06-01",
}

Alternatively, you can do a conversion for at a specific date

const response = layer.convert("USD", "GBP", 100.00, "2019-01-21")

Timeseries

Timeseries: you may request historical exchange rates for a time-period of your choice. (maximum range: 365 days)

Signature:

timeseries(start: RequestDate, end: RequestDate, symbols: BaseType[]): Promise<Timeseries>

Example:

const response = layer.timeseries("2019-06-01", new Date(), ["GBP", "NGN"])

console.log("response:", response)

Response:

{
  success: true,
  timeseries: true,
	start_date: "2019-06-01",
	end_date: "2019-06-04",
	base: "USD",
	rates: {
    "2019-06-01": {"USDGBP": 0.82, "USDNGN": 365.03},
    "2019-06-02": {"USDGBP": 0.82, "USDNGN": 366.51},
    "2019-06-03": {"USDGBP": 0.82, "USDNGN": 365.3},
    "2019-06-04": {"USDGBP": 0.82, "USDNGN": 366.01},
  }
}

Fluctuation

Fluctuation request the change (both margin and percentage) of one or more currencies, relative to a Source Currency, within a specific time-frame

Signature:

fluctuation(
  start: RequestDate,
  end: RequestDate,
  symbols: BaseType[]
): Promise<Fluctuation>

Example:

const response = layer.fluctuation("2019-06-01", new Date(), ["GBP", "NGN"])

console.log("response:", response)

Response:

{
  success: true,
  fluctuation: bool
	start_date: "2019-06-01"
	end_date: "2019-06-02"
	base: "USD"
	rates: {
    "USDGBP": {
      start_rate: 0.82,
      end_rate: 0.81,
      change: 0.01,
      change_pct: 1.21,
    },
    "USDNGN": {
      start_rate: 366.60,
      end_rate: 364.25,
      change: 2.35,
      change_pct: 0.64,
    }
  }
}

Supported Currencies

A list of all supported currencies can be displayed by:

layer.symbols()

Or, you can see a list of all supported currencies below:

License

MIT