currency-data

currency-data

Currency data is an npm package for exposing information about the world's currencies and their usage. It's core value lies in ./data.json and it exposes a number of utility methods for interacting with it's content, however, requiring that data yourself is of course possible (and encouraged). You can do so thusly:

const rawCurrencyData = require('./node_modules/currency-data/data'); 

There are a number of other NPM modules that have similar functionality, but most of them have incomplete data (e.g. only returning one currency that uses the '£' symbol?! There are dozens!). As a result this module attempts to offer a complete and comprehensive set of data about the worlds currencies.

Need information about the currency used in the Nagorno-Karabakh Republic? This is the module for you! The answer is it uses two currencies: the Nagorno-Karabakh Dram and the Armenian Dram!

Usage

const currencyData = require('currency-data');
 
currencyData.getCurrenciesBySymbol('£'); // Returns an Array of all currencies that use the '£' symbol

Data structure

The core data structure is as follows:

{
    "countryName": "United States",
    "countryISOCode":"USA",
    "currency": { 
        "name": "United States Dollar",
        "symbol": "$",
        "isoCode": "USD",
        "fractionalUnit": {
            "name":"Cent",
            "numberToBasic":100
        }
    }
}
 

The public API

The public API is very high level, and frankly, verbose. It was deliberatley designed that way to be self explanatory. I know I got confused with the different ISO standards for describing counties and currencies, so I wanted to make the public methods eaiser to grok.

API Method	Arguments	Return type	Description
.getData()	None	Array	A utility method to return all of the data from the module in a single large Array
.getCurrencyByCountryISOCode()	String / An ISO 3166-1 alpha-3 country code	Object	Returns the currency used in a specified country
.getCountriesByCurrencyISOCode()	String / An ISO_4217 currency code	Array	Returns an Array of country objects that use a currency e.g. all the countries that use the USD
.getCurrencyByCurrencyISOCode()	String / An ISO_4217 currency code	Object	Returns just the currency object (see Data Structure above) for a currency
.getCurrenciesBySymbol()	String / a currency symbol e.g. $/£/€	Array	Returns an Array of all currencies that use that symbol
.getCurrencyByName()	String e.g. British Pound	Object	Returns just the currency object (see Data Structure above) for a currency
.getCurrenciesByFractionalUnit()	String e.g. Cent	Array	Returns an Array of all the currencies that use a fractional unit
.getCurrenciesByFractionalUnitNumberToBasic()	Integer e.g. 100	Array	A niche method, but it returns all the currencies that share the property of number of fractional units to a basic unit
.getCurrencyISOCodes()	None	Array	Utility method that returns all of the available currency ISO codes, please remember some currencies do not have assigned ISO codes and so won't be returned
.getCurrencyNames()	None	Array	Utility method that returns the names of all the available currencies
.getCountryISOCodes()	None	Array	Utility method that returns the names of the ISO codes of all available countries
.getCountryNames()	None	Array	Utility method that returns the names of the all the available countries

If you have any requests for public methods please file an issue, these were created to meet my own use case for this module but I can see how others would also be useful.

Testing

npm test
npm local-coverage // runs tests and generates coverage report

TODO

• Return all available currency denominations for a currency

Contrubuting

All contributors will abide by the CODE_OF_CONDUCT.md.

License

MIT