@apilayer/currencylayer v0.1.6

currencylayer-js

Currencylayer offers Reliable Exchange Rates & Currency Conversion for your Business

Installation

Using npm

npm install --save @apilayer/currencylayer

or yarn

yarn add @apilayer/currencylayer

Getting Started

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

import Currencylayer from '@apilayer/currencylayer';

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

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

layer.setSource("GBP")

Unsupported currency codes with throw an error.

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

import Currencylayer, { SourceType } from '@apilayer/currencylayer';

const layer = new Currencylayer({
  ...
  source: SourceType.USD,
})

Note:

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

Live rates

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

Signature:

live(sources: SourceType[]): Promise<LiveResponse>

Example:

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

console.log("response:", response)

Response:

{
	success: true,
	timestamp: 1566902074,
	source: "USD",
	quotes: {
    "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, sources: SourceType[] = []): Promise<HistoricalResponse>

Example:

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

console.log("response:", response)

Response:

{
  success: true,
	historical: true,
	timestamp: 1566902074,
  source: "USD",
  date: "2019-06-01",
	quotes: {
    "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: SourceType,
  to: SourceType,
  amount: number,
  date: RequestDate = new Date()
): Promise<ConvertResponse>

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,
    quote: 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")

Timeframe

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

Signature:

timeframe(
  start: RequestDate,
  end: RequestDate,
  sources: SourceType[]
): Promise<TimeframeResponse>

Example:

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

console.log("response:", response)

Response:

{
  success: true,
  timeframe: true,
	start_date: "2019-06-01",
	end_date: "2019-06-04",
	source: "USD",
	quotes: {
    "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},
  }
}

Change

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

Signature:

change(start: RequestDate, end: RequestDate, sources: SourceType[]): Promise<ChangeResponse>

Example:

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

console.log("response:", response)

Response:

{
  success: true,
  change: bool
	start_date: "2019-06-01"
	end_date: "2019-06-02"
	source: "USD"
	quotes: {
    "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.list()

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

License

MIT