fixer-api v2.2.7

fixer.io API client for Node.js and browser in TypeScript

Features

• works in both Node.js and browser
• promise or async / await based
• extensively tested with unit and integration tests.

API key

To use fixer API, you must obtain an Access Key first https://fixer.io/.

Install

npm install fixer-api

Usage

• Latest
• Historical
• Conversion
• Timeseries
• Available symbols (currencies)

Import default fixer instance

const fixer = require("fixer-api");

Set accessKey obtained from fixer.io

fixer.set({ accessKey: "<YOUR API KEY>" });

.set supports chaining, so you can run a query right after, e.g.:

await fixer.set({ accessKey: "<YOUR API KEY>" }).latest();

Fetch the latest data with .latest

const data = await fixer.latest();
console.log(data);

/**
 *  or, if you want to specify access key per request (note it's in snake_case here)
 */
const data = await fixer.latest({ access_key: '<YOUR API KEY>' });
console.log(data);

/*
{
  base: 'EUR',
  date: '2017-01-30',
  rates: {
    AUD: 1.4109,
    BGN: 1.9558,
    BRL: 3.3318,
    CAD: 1.3983,
    CHF: 1.0669,
    CNY: 7.3103,
    CZK: 27.022,
    DKK: 7.4375,
    GBP: 0.84935,
    HKD: 8.2476,
    HRK: 7.4773,
    HUF: 310.8,
    IDR: 14173,
    ILS: 4.0228,
    INR: 72.232,
    JPY: 121.76,
    KRW: 1252.3,
    MXN: 22.085,
    MYR: 4.7094,
    NOK: 8.8758,
    NZD: 1.4668,
    PHP: 52.899,
    PLN: 4.331,
    RON: 4.5008,
    RUB: 63.779,
    SEK: 9.439,
    SGD: 1.5177,
    THB: 37.492,
    TRY: 4.0561,
    USD: 1.063,
    ZAR: 14.451
  }
}
/*

Fetch latest data based on specific base currency

const data = await fixer.latest({ base: "USD", symbols: ["CHF"] });
console.log(data);

/*
{ base: 'USD', date: '2017-01-30', rates: { CHF: 1.0037 } }
*/

Fetching historical data with .forDate

const data = await fixer.forDate('2015-04-01', { base: 'USD', symbols: ['CHF'] });

/**
 *  or, if you want to specify access key per request (note it's in snake_case here)
 */
const data = await fixer.forDate('2015-04-01', {
  access_key: '<YOUR API KEY>', ]
  base: 'USD',
  symbols: ['CHF']
});
console.log(data);

or by providing Date instance:

const data = await fixer.forDate(new Date(), { base: "USD", symbols: ["CHF"] });

Doing currency conversion with .convert

Keep in mind that .convert requires a paid fixer plan.

fixer.convert(<from>, <to>, <amount>, <date? = current date>)

const data = await fixer.convert("GBP", "JPY", 25, "2018-02-22");
console.log(data);

/*
  success: true,
  query: {
    from: "GBP",
    to: "JPY",
    amount: 25
  },
  info: {
    timestamp: 1519328414,
    rate: 148.972231
  },
  date: "2018-02-22"
  result: 3724.305775
*/

Fetching available symbols with .symbols

const data = await fixer.symbols({
  access_key: '<YOUR API KEY>',
});
console.log(data);

/*
{
  success: true,
  symbols: {
    AED: 'United Arab Emirates Dirham',
    AFN: 'Afghan Afghani',
    ALL: 'Albanian Lek',
    AMD: 'Armenian Dram',
    ANG: 'Netherlands Antillean Guilder',
    ...
  }
}
*/

Fetching historical rates with .timeseries

const data = await fixer.timeseries(
  '2012-05-01',
  '2012-05-25',
  {
    // optionally pass base currency
    base: 'EUR',
    // optionally pass symbols to query rates for
    symbols: ['USD', 'AUD', 'CAD'],
    // optionally pass assess key
    access_key: '<YOUR API KEY>'
  }
);
console.log(data);

/*
{
  success: true,
  timeseries: true,
  start_date: '2012-05-01',
  end_date: '2012-05-03',
  base: 'EUR',
  rates: {
    '2012-05-01': {
      USD: 1.322891,
      AUD: 1.278047,
      CAD: 1.302303,
    },
    '2012-05-02': {
      USD: 1.315066,
      AUD: 1.274202,
      CAD: 1.299083,
    },
    '2012-05-03': {
      USD: 1.314491,
      AUD: 1.280135,
      CAD: 1.296868,
    },
  },
}
*/

Running tests

Unit tests

Unit tests run in isolation and don't send real requests to fixer.io.

npm test

Integration tests

Integration tests send real requests to fixer.io and so require valid access key.

FIXER_API_KEY="<YOUR_FIXER_KEY_HERE>" npm run test:integration

Using in browser

dist folder of packaged npm module includes browser bundles: fixer.iife.js and fixer.iife.min.js (minified version). Each bundle exposes an instance of fixer as fixerApi global variable.

Typical usage is as follows (supposing web server is serving node-modules):

<body>
  <script src="node-modules/fixer-api/dist/fixer.iife.min.js"></script>
  <script>
    fixerApi
      .set({ accessKey: "<YOUR_FIXER_KEY_HERE>" })
      .latest()
      .then(result => {
        console.log(result);
      });
  </script>
</body>

or by using unpkg CDN:

<body>
  <script src="https://unpkg.com/fixer-api/dist/fixer.iife.min.js"></script>
  <script>
    fixerApi
      .set({ accessKey: "<YOUR_FIXER_KEY_HERE>" })
      .latest()
      .then(result => {
        console.log(result);
      });
  </script>
</body>