@apilayer/currencylayer

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:

Code	Name
AED	United Arab Emirates Dirham
AFN	Afghan Afghani
ALL	Albanian Lek
AMD	Armenian Dram
ANG	Netherlands Antillean Guilder
AOA	Angolan Kwanza
ARS	Argentine Peso
AUD	Australian Dollar
AWG	Aruban Florin
AZN	Azerbaijani Manat
BAM	Bosnia-Herzegovina Convertible Mark
BBD	Barbadian Dollar
BDT	Bangladeshi Taka
BGN	Bulgarian Lev
BHD	Bahraini Dinar
BIF	Burundian Franc
BMD	Bermudan Dollar
BND	Brunei Dollar
BOB	Bolivian Boliviano
BRL	Brazilian Real
BSD	Bahamian Dollar
BTC	Bitcoin
BTN	Bhutanese Ngultrum
BWP	Botswanan Pula
BYR	Belarusian Ruble
BZD	Belize Dollar
CAD	Canadian Dollar
CDF	Congolese Franc
CHF	Swiss Franc
CLF	Chilean Unit of Account (UF)
CLP	Chilean Peso
CNY	Chinese Yuan
COP	Colombian Peso
CRC	Costa Rican Colón
CUC	Cuban Convertible Peso
CUP	Cuban Peso
CVE	Cape Verdean Escudo
CZK	Czech Republic Koruna
DJF	Djiboutian Franc
DKK	Danish Krone
DOP	Dominican Peso
DZD	Algerian Dinar
EGP	Egyptian Pound
ERN	Eritrean Nakfa
ETB	Ethiopian Birr
EUR	Euro
FJD	Fijian Dollar
FKP	Falkland Islands Pound
GBP	British Pound Sterling
GEL	Georgian Lari
GGP	Guernsey Pound
GHS	Ghanaian Cedi
GIP	Gibraltar Pound
GMD	Gambian Dalasi
GNF	Guinean Franc
GTQ	Guatemalan Quetzal
GYD	Guyanaese Dollar
HKD	Hong Kong Dollar
HNL	Honduran Lempira
HRK	Croatian Kuna
HTG	Haitian Gourde
HUF	Hungarian Forint
IDR	Indonesian Rupiah
ILS	Israeli New Sheqel
IMP	Manx pound
INR	Indian Rupee
IQD	Iraqi Dinar
IRR	Iranian Rial
ISK	Icelandic Króna
JEP	Jersey Pound
JMD	Jamaican Dollar
JOD	Jordanian Dinar
JPY	Japanese Yen
KES	Kenyan Shilling
KGS	Kyrgystani Som
KHR	Cambodian Riel
KMF	Comorian Franc
KPW	North Korean Won
KRW	South Korean Won
KWD	Kuwaiti Dinar
KYD	Cayman Islands Dollar
KZT	Kazakhstani Tenge
LAK	Laotian Kip
LBP	Lebanese Pound
LKR	Sri Lankan Rupee
LRD	Liberian Dollar
LSL	Lesotho Loti
LTL	Lithuanian Litas
LVL	Latvian Lats
LYD	Libyan Dinar
MAD	Moroccan Dirham
MDL	Moldovan Leu
MGA	Malagasy Ariary
MKD	Macedonian Denar
MMK	Myanma Kyat
MNT	Mongolian Tugrik
MOP	Macanese Pataca
MRO	Mauritanian Ouguiya
MUR	Mauritian Rupee
MVR	Maldivian Rufiyaa
MWK	Malawian Kwacha
MXN	Mexican Peso
MYR	Malaysian Ringgit
MZN	Mozambican Metical
NAD	Namibian Dollar
NGN	Nigerian Naira
NIO	Nicaraguan Córdoba
NOK	Norwegian Krone
NPR	Nepalese Rupee
NZD	New Zealand Dollar
OMR	Omani Rial
PAB	Panamanian Balboa
PEN	Peruvian Nuevo Sol
PGK	Papua New Guinean Kina
PHP	Philippine Peso
PKR	Pakistani Rupee
PLN	Polish Zloty
PYG	Paraguayan Guarani
QAR	Qatari Rial
RON	Romanian Leu
RSD	Serbian Dinar
RUB	Russian Ruble
RWF	Rwandan Franc
SAR	Saudi Riyal
SBD	Solomon Islands Dollar
SCR	Seychellois Rupee
SDG	Sudanese Pound
SEK	Swedish Krona
SGD	Singapore Dollar
SHP	Saint Helena Pound
SLL	Sierra Leonean Leone
SOS	Somali Shilling
SRD	Surinamese Dollar
STD	São Tomé and Príncipe Dobra
SVC	Salvadoran Colón
SYP	Syrian Pound
SZL	Swazi Lilangeni
THB	Thai Baht
TJS	Tajikistani Somoni
TMT	Turkmenistani Manat
TND	Tunisian Dinar
TOP	Tongan Paʻanga
TRY	Turkish Lira
TTD	Trinidad and Tobago Dollar
TWD	New Taiwan Dollar
TZS	Tanzanian Shilling
UAH	Ukrainian Hryvnia
UGX	Ugandan Shilling
USD	United States Dollar
UYU	Uruguayan Peso
UZS	Uzbekistan Som
VEF	Venezuelan Bolívar Fuerte
VND	Vietnamese Dong
VUV	Vanuatu Vatu
WST	Samoan Tala
XAF	CFA Franc BEAC
XAG	Silver (troy ounce)
XAU	Gold (troy ounce)
XCD	East Caribbean Dollar
XDR	Special Drawing Rights
XOF	CFA Franc BCEAO
XPF	CFP Franc
YER	Yemeni Rial
ZAR	South African Rand
ZMK	Zambian Kwacha (pre-2013)
ZMW	Zambian Kwacha
ZWL	Zimbabwean Dollar

License

MIT