| View on npm | Try on Runkit | Website |
|---|
npm install freechange
This will include a few meg of historical json, so be warned we are very data heavy. See below for options to reduce this size.
var freechange = require("freechange")
console.log( freechange.by_date(100,"GBP","USD","2010") )
console.log( freechange.by_date(100,"GBP","USD","2010-01") )
console.log( freechange.by_date(100,"GBP","USD","2010-01-01") )
This will exchange 100 GBP to USD multiple times, using slightly different dates.
Remember, we have a focus on historical data so this call may give different results when used with a date less than a year old, depending on when you installed the package and when we last updated the package with newer data. This happens as new data is collected overtime.
Currencies are expressed as their ISO 4217 codes.
We currently have historical exchange rates for 190 currencies with varying degrees of support and resolution.
You can view this list by visiting https://xriss.github.io/freechange-charts/ and selecting from USD to your currency of choice.
The monthly chart represents good coverage so if that is missing then we do not support that currency very well.
So to recap, times in the past are good and stable, times in the future
are not.
If you mostly care about today's exchange rates, you
should be using an API rather than this historical data dump.
When you provide a date, it will trigger one of three modes as described below - depending on if it is a full date, a month or a year only.
We will use yearly averages for the given year or closest year if it is out of the range of data.
We will use monthly averages for the given month or switch to yearly average if the date is out of the range of our monthly data.
We will use daily numbers for the given day or switch to monthly and then yearly average if the date is out of the range of our data.
This function will return a number if it is successful or undefined if it is not; eg. we could not find the currency you requested.
If you want to reduce the amount of memory used by data, you can reduce the maximum resolution from day to month or year by changing to one of the following requires. This allows you to explicitly choose the resolutions available to reduce accuracy and more importantly, data size.
var freechange = require("freechange/day")
var freechange = require("freechange/month")
var freechange = require("freechange/year")
When it comes to sourcing the data we use ( in order of preference )
numbers from the following sources. You can find the latest data we
grabbed in the JSON directory along with generated usd_to_xxx exchange
rates for days, months and years.
| Name | Range | Source | JSON |
|---|---|---|---|
| IMF | Daily | https://www.imf.org/external/np/fin/data/param_rms_mth.aspx | https://github.com/xriss/freechange/blob/master/json/imf.json |
| FRED | Daily | https://fred.stlouisfed.org/categories/94 | https://github.com/xriss/freechange/blob/master/json/fred.json |
| CodeforIATI | Daily | https://raw.githubusercontent.com/codeforIATI/imf-exchangerates/gh-pages/imf_exchangerates.csv | https://github.com/xriss/freechange/blob/master/json/cfiati.json |
| OECD | Monthly | https://data.oecd.org/conversion/exchange-rates.htm | https://github.com/xriss/freechange/blob/master/json/oecd.json |
| MYBUTT | Yearly | https://github.com/xriss/freechange/blob/master/mybutt/year.csv | This folder contains handmade CSV for when every other source fails. |
All of these sources are combined into the following output JSON files
which contain data you could use directly outside of this module.
CSV files are also built at the same time as the JSON files and will
contain the same data.