![PyPI version](https://img.shields.io/pypi/v/nbg-currencies-api?color=blue&label=PyPI&logo=python&logoColor=white)
# NBG Currency Service

`NBGCurrencyService` is a Python library designed to fetch and normalize currency exchange rates from the National Bank of Georgia (NBG) API. It provides both synchronous and asynchronous functionality, making it suitable for various applications.

---

## Features

- Fetch exchange rates for the current date or a specific date.
- Retrieve rates for all currencies or a specific currency.
- Supports both synchronous and asynchronous modes.
- Easy-to-use interface with well-structured data models.

---

## Installation

### Install the package

```bash
pip install nbg-currency-api
```

### For Asynchronous Support

To enable async mode, install with the optional `aiohttp` dependency:

```bash
pip install nbg-currency-api[async]
```

---

## Usage

### Synchronous Mode

Fetch rates for all currencies on the current date:

```python
from nbg_currency_api import NBGCurrencyService

service = NBGCurrencyService()
data = service.fetch()
print(data)
```

Fetch rates for a specific currency on a specific date:

```python
from datetime import datetime
from nbg_currency_api import NBGCurrencyService, CurrencyEnum

service = NBGCurrencyService(
    date=datetime(2023, 12, 25), currency=CurrencyEnum.USD
)
data = service.fetch()
print(data)
```

---

### Asynchronous Mode

Fetch rates asynchronously for a specific currency:

```python
import asyncio
from nbg_currency_api import NBGCurrencyService, CurrencyEnum

async def main():
    service = NBGCurrencyService(currency=CurrencyEnum.EUR, mode="ASYNC")
    data = await service.afetch()
    print(data)

asyncio.run(main())
```

---

## Data Models

### `CurrencyDataResponse`

This is the structured response returned by the service after fetching and normalizing data.

| Field           | Type              | Description                     |
|------------------|-------------------|---------------------------------|
| `date`          | `datetime`        | The date for the rates          |
| `currencies`    | `List[CurrencyRateItem]` | List of currency rate items   |

### `CurrencyRateItem`

Represents details of a single currency rate.

| Field           | Type       | Description                     |
|------------------|------------|---------------------------------|
| `code`          | `str`      | ISO code of the currency        |
| `quantity`      | `int`      | Quantity for the rate           |
| `rateFormated`  | `str`      | Formatted rate string           |
| `diffFormated`  | `str`      | Formatted difference string     |
| `rate`          | `float`    | Exchange rate                  |
| `name`          | `str`      | Currency name                  |
| `diff`          | `float`    | Rate difference                |
| `date`          | `datetime` | Date of the rate               |
| `validFromDate` | `datetime` | Start date for the rate         |

---

## Configuration

### Supported Currencies

The `CurrencyEnum` includes all ISO codes of supported currencies, such as:
- `CurrencyEnum.USD`
- `CurrencyEnum.EUR`
- `CurrencyEnum.GBP`

### Modes

- **`SYNC`** (default): Use synchronous requests with the `fetch` method.
- **`ASYNC`**: Use asynchronous requests with the `afetch` method.

---

## Example Output

Fetching exchange rates for USD:

```python
from nbg_currency_api import NBGCurrencyService, CurrencyEnum

service = NBGCurrencyService(currency=CurrencyEnum.USD)
data = service.fetch()

print(data)
```

Sample output:

```python
CurrencyDataResponse(
    date=datetime.datetime(2025, 1, 7, 0, 0),
    currencies=[
        CurrencyRateItem(
            code='USD',
            quantity=1,
            rateFormated='3.20',
            diffFormated='+0.02',
            rate=3.2,
            name='US Dollar',
            diff=0.02,
            date=datetime.datetime(2025, 1, 7, 0, 0),
            validFromDate=datetime.datetime(2025, 1, 6, 0, 0)
        )
    ]
)
```

---

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for more details.
