Freechange is a javascript module and data to perform historical currency exchange.

| View on npm | Try on Runkit | Website |
|- |- |- |

$3

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.

Options

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.

$3

We will use yearly averages for the given year or closest
year if it is out of the range of data.

$3

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.

$3

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")

Sources

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.

Data Downloads

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.