Exchange Rates

npm NPM Travis (.org)

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

Table of Contents

📦 Installation

$ npm i exchange-rates-api

⌨️ Usage

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

Latest & specific date rates

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

const example = 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
};

example();

Rates history

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

const example = 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');
};

example();

Different ways to pass a date

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

const example = 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();
};

example();

Currencies object

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

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

example();

Average rate for a specific time period

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

const example = 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 }
};

example();

Convert

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

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

example();

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.exchangeratesapi.io/history?start_at=2018-01-01&end_at=2018-09-01&base=USD&symbols=EUR,GBP

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
const example = 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
    }
};

example();

// 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

🧪 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

🎉 Credits

  • Thanks to @madisvain and all of the Exchange Rates API contributors for creating this awesome API
  • A big chunk of this README was heavily ~stolen from~ inspired by this repo, an API wrapper for PHP

📖 License

The MIT License, check the LICENSE file