@tigranyeritsyan/exchange-rates-api

Exchange Rates

💰🌍 An unofficial node.js wrapper for the awesome and free ratesapi.io, which provides exchange rate lookups courtesy of the Central European Bank.

Table of Contents

• Installation
• Usage
• Supported Currencies
• Bugs & Features
• Documentation
• Unit Testing
• Dependencies
• License

📦 Installation

$ npm i exchange-rates-api

⌨️ Usage

Once you have installed the npm package you can start using it immediately. Rates API does not require you to sign up, generate API keys etc.

Latest & specific date rates

const { exchangeRates } = require('exchange-rates-api');

(async () => {
    // Get the latest exchange rates
    await exchangeRates().latest().fetch();                             // {THB: 34.978, PHP: 58.159, …, HUF: 323.58}

    // Get historical rates for any day since 1999
    await exchangeRates().at('2018-03-26').fetch();                     // {THB: 38.66, PHP: 64.82, …, HUF: 312.73}

    // By default, the base currency is EUR, but it can be changed
    await exchangeRates().latest().base('USD').fetch();                 // {THB: 30.9348191386, …, HUF: 286.1767046962}

    // Request specific exchange rates
    await exchangeRates().latest().symbols(['USD', 'GBP']).fetch();     // {USD: 1.1307, GBP: 0.89155}

    // Request one specific exchange rate
    await exchangeRates().latest().symbols('USD').fetch();              // 1.1307
})();

Rates history

const { exchangeRates } = require('exchange-rates-api');

(async () => {
    // Get historical rates for a time period
    await exchangeRates().from('2018-01-01').to('2018-09-01').fetch();
    // outputs: { '2018-02-28': { THB: 38.613, …, HUF: 313.97 }, …, { '2018-06-07': { … } } }

    // Limit results to specific exchange rates to save bandwidth
    await exchangeRates()
        .from('2018-01-01').to('2018-09-01')
        .symbols(['ILS', 'JPY'])
        .fetch();

    // Quote the historical rates against a different currency
    await exchangeRates().from('2018-01-01').to('2018-09-01').base('USD');
})();

Different ways to pass a date

const { exchangeRates } = require('exchange-rates-api');

(async () => {
    // Pass an YYYY-MM-DD (ISO 8601) string
    await exchangeRates().at('2018-09-01').fetch();

    // Pass another string
    await exchangeRates().at('September 1, 2018').fetch();

    // Pass a Date object
    await exchangeRates().at(new Date(2019, 8, 1)).fetch();
})();

Currencies object

const { exchangeRates, currencies } = require('exchange-rates-api');

(async () => {
    await exchangeRates().latest()
        .base(currencies.USD)
        .symbols([currencies.EUR, currencies.GBP])
        .fetch();
})();

Average rate for a specific time period

const { exchangeRates } = require('exchange-rates-api');

(async () => {
    // Find the average exchange rate for January, 2018
    await exchangeRates()
        .from('2018-01-01').to('2018-01-31')
        .base('USD').symbols('EUR')
        .avg();     // 0.8356980613403501

    // Set the number of decimal places
    await exchangeRates()
        .from('2018-01-01').to('2018-01-31')
        .base('USD').symbols(['EUR', 'GBP'])
        .avg(2);    // { EUR: 0.84, GBP: 0.74 }
})();

Convert

const { convert } = require('exchange-rates-api');

(async () => {
    let amount = await convert(2000, 'USD', 'EUR', '2018-01-01');
    console.log(amount);    // 1667.6394564000002
})();

API URL

const { exchangeRates } = require('exchange-rates-api');

// Grab the url we're going to request
let url = exchangeRates()
    .from('2018-01-01').to('2018-09-01')
    .base('USD').symbols(['EUR', 'GBP'])
    .url;

console.log(url);
// https://api.ratesapi.io/history?start_at=2018-01-01&end_at=2018-09-01&base=USD&symbols=EUR,GBP

Using a different API

const { exchangeRates } = require('exchange-rates-api');

/* You can use it with pretty much any Fixer.io-compatible API */

(async () => {
    await exchangeRates()
        .setApiBaseUrl('https://api.exchangerate.host')
        .latest()
        .fetch();    // {THB: 34.978, PHP: 58.159, …, HUF: 323.58}
})();

Error handling

const { exchangeRates } = require('exchange-rates-api');

/* `ExchangeRatesError` and `TypeError` are explicitly thrown
 * sometimes, so you might want to handle them */

// async/await syntax
(async () => {
    try {
        /* This will throw an `ExchangeRateError` with the error
         * message 'Cannot get historical rates before 1999' */
        let rates = await exchangeRates().at('1990-01-01').fetch();
    } catch (error) {
        // Handle the error
    }
})();

// Promises syntax
exchangeRates().at('1990-01-01').fetch()
    .then(rates => {})
    .catch(error => {
        // Handle the error
    });

💰 Supported Currencies

The library supports any currency currently available on the European Central Bank's web service, which at the time of the latest release are as follows:

• Australian Dollar (AUD)
• Brazilian Real (BRL)
• British Pound Sterline (GBP)
• Bulgarian Lev (BGN)
• Canadian Dollar (CAD)
• Chinese Yuan Renminbi (CNY)
• Croatian Kuna (HRK)
• Czech Koruna (CZK)
• Danish Krone (DKK)
• Euro (EUR)
• Hong Kong Dollar (HKD)
• Hungarian Forint (HUF)
• Icelandic Krona (ISK)
• Indonesian Rupiah (IDR)
• Indian Rupee (INR)
• Israeli Shekel (ILS)
• Japanese Yen (JPY)
• Malaysian Ringgit (MYR)
• Mexican Peso (MXN)
• New Zealand Dollar (NZD)
• Norwegian Krone (NOK)
• Philippine Peso (PHP)
• Polish Zloty (PLN)
• Romanian Leu (RON)
• Russian Rouble (RUB)
• Singapore Dollar (SGD)
• South African Rand (ZAR)
• South Korean Won (KRW)
• Swedish Krona (SEK)
• Swiss Franc (CHF)
• Thai Baht (THB)
• Turkish Lira (TRY)
• US Dollar (USD)

🐞 Bugs & Features

If you have spotted any bugs, or would like to request additional features from the library, please file an issue.

📚 Documentation

• Read the docs

• Generate them using jsdoc

  $ npm run docs
  

🧪 Unit Testing

There are a few basic unit tests in the test directory, but we should definitely write more

Development dependencies

• Chai — a BDD / TDD assertion library for node and the browser
• Mocha — a feature-rich JavaScript test framework running on Node.js and in the browser
• fetch-mock — allows mocking http requests made using fetch or a library imitating its api, such as node-fetch or fetch-ponyfill

🗄 Dependencies

• date-fns — Modern JavaScript date utility library
• isomorphic-fetch — Isomorphic WHATWG Fetch API, for Node & Browserify

📖 License

The MIT License, check the LICENSE file