fixer-api
v2.2.6
Published
fixer.io API client in TypeScript
Downloads
4,409
Maintainers
Readme
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
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>