node-currency-exchange-rates

Open-source project designed to provide exchange rates and offer a simple currency conversion experience.

Supported currencies

The following currencies are supported. You can get exchange rates or convert currency values between them:

Installation

npm install node-currency-exchange-rates

Linux

Please make sure you have these packages installed to run this package correctly:

apt install -y gconf-service libgbm-dev libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget

Usage

getRates([baseCurrency='USD'])

• Returns exchange rates for given currency.

• Receives one optional parameter:

  • baseCurrency - must be a valid currency.

    • Default value is USD.

* Valid currencies are listed here.

Valid usage examples:

Without baseCurrency optional parameter:

import exchange from 'node-currency-exchange-rates';

const example = async () => {
  const rates = await exchange.getRates();
  console.log(rates);
};

example();

With baseCurrency optional parameter:

import exchange from 'node-currency-exchange-rates';

const example = async () => {
  const rates = await exchange.getRates('USD');
  console.log(rates);
};

example();

Output:

{
  baseCurrency: 'USD',
  baseValue: 1,
  date: 2023-07-22T21:41:40.446Z,
  exchangeRates: [
    { JPY: 141.81 },
    { CHF: 0.8659 },
    { CAD: 1.3222 },
    { ZAR: 17.948 },
    { TRY: 26.9381 },
    { MXN: 16.976 },
    { PLN: 4.0075 },
    { SEK: 10.3821 },
    { SGD: 1.3305 },
    { DKK: 6.6964 },
    { NOK: 10.066 },
    { ILS: 3.6276 },
    { HUF: 340.46 },
    { CZK: 21.5381 },
    { THB: 34.0055 },
    { AED: 3.6719 },
    { KWD: 0.3066 },
    ...
  ]
}

convert(fromCurrency, fromValue, toCurrency)

• Returns the converted value using the given currencies.

• Receives 3 required parameters:

  • fromCurrency - valid base currency;
  • fromValue - value to be converted;
  • toCurrency - valid currency.

* Valid currencies are listed here.

Valid usage example:

import exchange from 'node-currency-exchange-rates';

const example = async () => {
  // convert 100 USD to EUR
  const convertedValue = await exchange.convert('USD', 100, 'EUR');
  console.log(convertedValue);
};

example();

Output:

89.88

Data caching

By default this package uses local JSON files to cache currency rates data.

All cached data is refreshed hourly, so you'll always have up to date rates.

v1.0.7+

In v1.0.7 or newer versions, you can also use Redis to cache data instead of using the default caching strategy.

Click here to see a complete example of implementation using Redis for data caching.

Redis caching example:

import { Exchange } from 'node-currency-exchange-rates';

// must be a valid Redis connection string
const REDIS_DATABASE_URL = 'redis://johndoe:[email protected]:6379';

const exchange = new Exchange(REDIS_DATABASE_URL);

const example = async () => {
  const rates = await exchange.getRates('USD');
  console.log(rates);
};

example();

Output:

{
  baseCurrency: 'USD',
  baseValue: 1,
  date: 2023-07-22T21:41:40.446Z,
  exchangeRates: [
    { JPY: 141.81 },
    { CHF: 0.8659 },
    { CAD: 1.3222 },
    { ZAR: 17.948 },
    { TRY: 26.9381 },
    { MXN: 16.976 },
    { PLN: 4.0075 },
    { SEK: 10.3821 },
    { SGD: 1.3305 },
    { DKK: 6.6964 },
    { NOK: 10.066 },
    { ILS: 3.6276 },
    { HUF: 340.46 },
    { CZK: 21.5381 },
    { THB: 34.0055 },
    { AED: 3.6719 },
    { KWD: 0.3066 },
    ...
  ]
}

Change logs

v1.1.0

You can set the currency rates refresh interval. Valid intervals are 6h, 12h or 24h. Default value is 1h.

Set currency rates refresh interval example:

import { Exchange } from 'node-currency-exchange-rates';

const exchange = new Exchange();

exchange.refreshRatesInterval = '24h';

const example = async () => {
  const rates = await exchange.getRates('USD');
  console.log(rates);
};

example();

Output:

{
  baseCurrency: 'USD',
  baseValue: 1,
  date: 2023-07-22T21:41:40.446Z,
  exchangeRates: [
    { JPY: 141.81 },
    { CHF: 0.8659 },
    { CAD: 1.3222 },
    { ZAR: 17.948 },
    { TRY: 26.9381 },
    { MXN: 16.976 },
    { PLN: 4.0075 },
    { SEK: 10.3821 },
    { SGD: 1.3305 },
    { DKK: 6.6964 },
    { NOK: 10.066 },
    { ILS: 3.6276 },
    { HUF: 340.46 },
    { CZK: 21.5381 },
    { THB: 34.0055 },
    { AED: 3.6719 },
    { KWD: 0.3066 },
    ...
  ]
}

License

MIT License

Copyright (c) 2023

Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.