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

1. Install NPM packages

   npm install node-mnb

2. 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

• [x] Add Changelog
• [x] Add back-to-top links
• [x] Add Additional Templates w/ Examples
• [x] 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!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m '✨ feat: Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request
6. Wait. :D

License

The name MNB and corresponding logos are a trademark of MNB (Hungarian National Bank).

Distributed under the GPL v3 License. See LICENSE.md for more information.

Contact

Andrew Black / Andras Fekete - @itslemonandrew - [email protected]

Project Link: https://github.com/0xAndrewBlack/node-mnb

Acknowledgments

Use this space to list resources you find helpful and would like to give credit to. I've included a few of my favorites to kick things off!

• mondalaci - Starter WSDL method source.
• Choose an Open Source License - License template
• README Template - Readme template
• GitHub Emoji Cheat Sheet - Emojis