Skip to content

Node package that retrieves information from the Hungarian National Bank's (MNB) SOAP API.

License

Notifications You must be signed in to change notification settings

0xAndrewBlack/node-mnb

Contributors Forks Stargazers Issues MIT License


Logo

node-mnb

An awesome package to help you communicate with the MNB's SOAP API.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contributing
  6. License
  7. Contact
  8. Acknowledgments

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

(back to top)

Built With

The project is built with a few packages.

(back to top)

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

(back to top)

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.

(back to top)

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

(back to top)

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

(back to top)

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.

(back to top)

Contact

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

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

(back to top)

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!

(back to top)

About

Node package that retrieves information from the Hungarian National Bank's (MNB) SOAP API.

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Packages

No packages published