fxratesapi v1.0.2

Exchange Rates

💰🌍 An unofficial node.js wrapper for the awesome and free fxratesapi.com, which provides exchange rate lookups for over 175 global currencies updated every minute.

Table of Contents

• Installation
• Usage
• Supported Currencies
• Dependencies
• License

📦 Installation

$ npm i fxratesapi

⌨️ Usage & Authentication

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

However, if you want to use the convert method, you need to sign up for a free account and get an API key. The API key is not required for the other methods. You are also subject to lower rate limits if you don't use an API key.

📡 Endpoints

Latest & specific date rates

const fxRatesAPI  = require("fxratesapi");
const fx = new fxRatesAPI('apikey'); // api key is not required

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

    // Get historical rates for any day since 1999
    await fx.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 fx.latest().base('USD').fetch();                 // {THB: 30.9348191386, …, HUF: 286.1767046962}

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

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

Rates history

const fxRatesAPI  = require("fxratesapi");
const fx = () => new fxRatesAPI("apikey"); // api key is not required

(async () => {
    // Get historical rates for a time period
    await fx().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 fx()
        .from('2018-01-01').to('2018-09-01')
        .symbols(['ILS', 'JPY'])
        .fetch();

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

Different ways to pass a date

const fxRatesAPI  = require("fxratesapi");
const fx = () => new fxRatesAPI("apikey"); // api key is not required

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

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

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

Currencies object

const fxRatesAPI  = require("fxratesapi");
const fx = new fxRatesAPI('apikey'); // api key is not required

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

Average rate for a specific time period

const fxRatesAPI  = require("fxratesapi");
const fx = () => new fxRatesAPI("apikey"); // api key is not required

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

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

Convert

conconst fxRatesAPI  = require("fxratesapi");
const fx = () => new fxRatesAPI("apikey"); // api key is not required

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

API URL

const fxRatesAPI  = require("fxratesapi");
const fx = () => new fxRatesAPI("apikey"); // api key is not required

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

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

Error handling

const fxRatesAPI  = require("fxratesapi");
const fx = () => new fxRatesAPI("apikey"); // api key is not required

/* `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 fx().at('1990-01-01').fetch();
    } catch (error) {
        // Handle the error
    }
})();

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

💰 Supported Currencies

This list has been last updated on 22. November 2023. For the latest list, please check the currency list on the fxratesapi website.

The library supports all 184 currencies listed on the fxratesapi website. The following table lists all supported currencies, their currency codes, and their symbols:

🗄 Dependencies

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

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

📖 License

The MIT License, check the LICENSE file