npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@tigranyeritsyan/exchange-rates-api

v1.1.1

Published

An API wrapper around exchangeratesapi.io

Downloads

251

Readme

Exchange Rates

npm NPM Travis (.org)

💰🌍 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

$ 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

🧪 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