Node-mnb NPM | npm.io

About The Project

The project started from a private software where I need to communicate and query up-to-date exchange information and it happened to be the MNB's SOAP API.

Why did I made it into a package?

Here's why:

The SOAP protocol is kind of deprecated and clunky, I solve it by providing a cool package that gives you it in a JSON format, and some types for my beloved TypeScript fans. 💪
Built-in types and cool documentation, unlike the official docs that you can't find anywhere if you ain't doing a google dork. LOL!
I wanted to make a useful node package for a long time and this was a great opportunity. :smile:

Built With

The project is built with a few packages.

soap - https://www.npmjs.com/package/soap
xml2js - https://www.npmjs.com/package/xml2js

Getting Started

This project is not affiliated with nor in contact with MNB. The package is a basic SOAP API "proxy" to communicate easily with the MNB's API without the hassle of writing a pile of classes and types and what not.

Types are right out of the box for easy working in TypeScript.

Prerequisites

Install the latest (at least v12) node, and install the package shown below.

npm v12.x
```
npm install npm@latest -g
```

Installation

Install NPM packages
```
npm install node-mnb
```
Use it

In CommonJS:

const { getMnbCurrencies } = require('node-mnb');

getMnbCurrencies().then((data) => console.log(data));

In TypeScript (we have builtin types from .d.ts)

import { getMnbCurrencies } from 'node-mnb';

getMnbCurrencies().then((data) => console.log(data));

Usage

getMnbCurrencies()

Get current queryable currencies.

[
  "HUF", "EUR", "AUD", "BGN", "BRL",
  "CAD", "CHF", "CNY", "CZK", "DKK",
  "GBP", "HKD", "HRK", "IDR", "ILS",
  "INR", "ISK", "JPY", "KRW", "MXN",
  "MYR", "NOK", "NZD", "PHP", "PLN",
  "RON", "RSD", "RUB", "SEK", "SGD",
  "THB", "TRY", "UAH", "USD", "ZAR",
  "ATS", "AUP", "BEF", "BGL", "CSD",
  "CSK", "DDM", "DEM", "EEK", "EGP",
  "ESP", "FIM", "FRF", "GHP", "GRD",
  "IEP", "ITL", "KPW", "KWD", "LBP",
  "LTL", "LUF", "LVL", "MNT", "NLG",
  "OAL", "OBL", "OFR", "ORB", "PKR",
  "PTE", "ROL", "SDP", "SIT", "SKK",
  "SUR", "VND", "XEU", "XTR", "YUD"
]

getMnbRates()

Get current exchange rates.

Note: The rates are calculated with it's unit so the corresponding unit per currency is calculated into it.

{
  "AUD": 269.37,
  "BGN": 202.47,
  "BRL": 73.63,
  "CAD": 302.26,
  "CHF": 405.23,
  "CNY": 57.55,
  "CZK": 16.07,
  "DKK": 53.2,
  "EUR": 396.01,
  "GBP": 473.36,
  "HKD": 49.52,
  "HRK": 52.68,
  "IDR": 0.026099999999999998,
  "ILS": 115.51,
  "INR": 4.92,
  "ISK": 2.84,
  "JPY": 2.9179000000000004,
  "KRW": 0.2964,
  "MXN": 18.79,
  "MYR": 87.21,
  "NOK": 40.01,
  "NZD": 243.25,
  "PHP": 6.98,
  "PLN": 84.22,
  "RON": 80.36,
  "RSD": 3.37,
  "RUB": 6.44,
  "SEK": 38.02,
  "SGD": 281.36,
  "THB": 10.72,
  "TRY": 21.64,
  "UAH": 10.52,
  "USD": 388.7,
  "ZAR": 23.23
}

getMnbStatus()

Get status and basic information about the API.

{
  "firstDate": "1949-01-03",
  "lastDate": "2022-08-03",
  "currencies": [
    "HUF", "EUR", "AUD", "BGN", "BRL",
    "CAD", "CHF", "CNY", "CZK", "DKK",
    "GBP", "HKD", "HRK", "IDR", "ILS",
    "INR", "ISK", "JPY", "KRW", "MXN",
    "MYR", "NOK", "NZD", "PHP", "PLN",
    "RON", "RSD", "RUB", "SEK", "SGD",
    "THB", "TRY", "UAH", "USD", "ZAR",
    "ATS", "AUP", "BEF", "BGL", "CSD",
    "CSK", "DDM", "DEM", "EEK", "EGP",
    "ESP", "FIM", "FRF", "GHP", "GRD",
    "IEP", "ITL", "KPW", "KWD", "LBP",
    "LTL", "LUF", "LVL", "MNT", "NLG",
    "OAL", "OBL", "OFR", "ORB", "PKR",
    "PTE", "ROL", "SDP", "SIT", "SKK",
    "SUR", "VND", "XEU", "XTR", "YUD"
  ]
}

getMnbDateInterval()

Get stored date interval.

{
  "startDate": "1949-01-03",
  "endDate": "2022-08-03"
}

getMnbHistoricalRates(startDate, endDate, currenciesString)

Get historical rates and units based on the supplied query.

For example query:

{
  "startDate": "2022-07-14",
  "endDate": "2022-08-03",
  "currencies": "EUR, USD, JPY"
}

Result:

{
  "EUR": { "unit": 1, "rate": 396.01 },
  "JPY": { "unit": 100, "rate": 291.79 },
  "USD": { "unit": 1, "rate": 388.7 }
}

For more examples, please refer to this README.md as a documentation.

Roadmap

Add Changelog
Add back-to-top links
Add Additional Templates w/ Examples
Add more tests.
Add undocumented methods/actions and document them.
Report useless features and methods to the MNB.

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what makes the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Refer to using conventional commits.

Don't forget to give the project a star! Thanks again!