[![NPM version][npm-image]][npm-url]

# node-tcmb

Simple Node.js wrapper for [TCMB API](https://www.tcmb.gov.tr/kurlar/today.xml).

## Getting Started

### Installation

---

```sh
npm install node-tcmb
```

### Setup

Basically require `node-tcmb` and start using it.

### Example

---

```javascript
const tcmb = require("node-tcmb");
..
const ratesToday = await tcmb.rates.today();
```

### Handling Weekends

TCMB does not contain any exchange rate data for weekends. This package handles this situation with retrieving the last friday's exchange rates for weekends.

For example: '17/11/2019' is a weekend day. This package will retrieve the data of '15/11/2019'.

### Handling National Holidays

TCMB does not contain any exchange rate data for national holidays. This package handles this situation with retrieving the last business day's exchange rates.

For example: '06/06/2019' is a national holiday. This package will retrieve the data of '31/05/2019'.

### Filtering

You can filter result rates by date (example format: DD/MM/YYYY) and currency code.

```javascript
const tcmb = require("node-tcmb");
..
// USD exchange rate of today.
const usdToday = await tcmb.rates.today("USD");

// All exchange rates of 01/01/2019.
const usdToday = await tcmb.rates.date("01/01/2019");

// USD exchange rate of 01/01/2019.
const usdPast = await tcmb.rates.date("01/01/2019", "USD");
```

##### Example Responses

---

##### Example of Listing All Exchange Rates

```json
{
    "date": "19/11/2019",
    "currencies": [
        {
            "attributes": {
                "crossOrder": "0",
                "kod": "USD",
                "currencyCode": "USD"
            },
            "unit": 1,
            "isim": "ABD DOLARI",
            "currencyName": "US DOLLAR",
            "forexBuying": 5.7153,
            "forexSelling": 5.7256,
            "banknoteBuying": 5.7113,
            "banknoteSelling": 5.7342,
            "crossRateUSD": null,
            "crossRateOther": null
        },
        {
            "attributes": {
                "crossOrder": "1",
                "kod": "AUD",
                "currencyCode": "AUD"
            },
            "unit": 1,
            "isim": "AVUSTRALYA DOLARI",
            "currencyName": "AUSTRALIAN DOLLAR",
            "forexBuying": 3.8825,
            "forexSelling": 3.9078,
            "banknoteBuying": 3.8646,
            "banknoteSelling": 3.9312,
            "crossRateUSD": 1.4686,
            "crossRateOther": null
        },
        {
            "attributes": {
                "crossOrder": "2",
                "kod": "DKK",
                "currencyCode": "DKK"
            },
            "unit": 1,
            "isim": "DANİMARKA KRONU",
            "currencyName": "DANISH KRONE",
            "forexBuying": 0.84555,
            "forexSelling": 0.84971,
            "banknoteBuying": 0.84496,
            "banknoteSelling": 0.85166,
            "crossRateUSD": 6.7487,
            "crossRateOther": null
        },
        {
            "attributes": {
                "crossOrder": "9",
                "kod": "EUR",
                "currencyCode": "EUR"
            },
            "unit": 1,
            "isim": "EURO",
            "currencyName": "EURO",
            "forexBuying": 6.3279,
            "forexSelling": 6.3393,
            "banknoteBuying": 6.3234,
            "banknoteSelling": 6.3488,
            "crossRateUSD": null,
            "crossRateOther": 1.1072
        },
        .
        .
        .
    ]
}
```

##### Example of a Single Exchange Rate

```json
{
  "date": "19/11/2019",
  "currency": {
    "attributes": {
      "crossOrder": "0",
      "kod": "USD",
      "currencyCode": "USD"
    },
    "unit": 1,
    "isim": "ABD DOLARI",
    "currencyName": "US DOLLAR",
    "forexBuying": 5.7153,
    "forexSelling": 5.7256,
    "banknoteBuying": 5.7113,
    "banknoteSelling": 5.7342,
    "crossRateUSD": null,
    "crossRateOther": null
  }
}
```

## Supported Currencies

| Code | Name                        |
| ---- | --------------------------- |
| USD  | US DOLLAR                   |
| AUD  | AUSTRALIAN DOLLAR           |
| DKK  | DANISH KRONE                |
| EUR  | EURO                        |
| GBP  | POUND STERLING              |
| CHF  | SWISS FRANK                 |
| SEK  | SWEDISH KRONA               |
| CAD  | CANADIAN DOLLAR             |
| KWD  | KUWAITI DINAR               |
| NOK  | NORWEGIAN KRONE             |
| SAR  | SAUDI RIYAL                 |
| JPY  | JAPENESE YEN                |
| BGN  | BULGARIAN LEV               |
| RON  | NEW LEU                     |
| RUB  | RUSSIAN ROUBLE              |
| IRR  | IRANIAN RIAL                |
| CNY  | CHINESE RENMINBI            |
| PKR  | PAKISTANI RUPEE             |
| QAR  | QATARI RIAL                 |
| XDR  | SPECIAL DRAWING RIGHT (SDR) |

## License

This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.

[npm-image]: https://img.shields.io/npm/v/node-tcmb.svg?style=flat
[npm-url]: https://www.npmjs.com/package/node-tcmb