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:

| 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