bddkdata 0.1.0
Fetches financial tables and banking sector data from the BRSA (BDDK) website.
License: MIT
Requires Python: >=3.8

# bddkdata v0.1.0

## Türkçe tercih edenler için:

***Those who prefer English can scroll down the page.***

## Açıklama

`bddkdata`, Bankacılık Düzenleme ve Denetleme Kurumu'nun (BDDK) resmi web sitesinde yayımlanan finansal tabloları ve bankacılık sektörü verilerini programatik olarak çekmeye olanak tanıyan bir Python kütüphanesidir. Kütüphane, aylık güncellenen temel bankacılık göstergelerine hızlı ve esnek erişim sağlar; veri analizi ve raporlama süreçlerinizi kolaylaştırır. Veriler doğrudan BDDK'nın açık veri servisinden alınır ve Türkçe/İngilizce başlık desteğiyle, kullanıma hazır pandas DataFrame formatında sunulur.

## Özellikler

* İstediğiniz tarih aralığında BDDK'nın yayımladığı aylık tabloları kolayca çekebilirsiniz.
* Tüm tablolar ve gruplar için Türkçe/İngilizce destekli başlıklarla veri alabilirsiniz.
* Kullanımı çok basittir, çıktı olarak doğrudan `pandas.DataFrame` döner.
* Hatalar ve mesajlar Türkçe veya İngilizce olarak gösterilir.
* Tablolar ve grup isimleri için kolayca listeleme fonksiyonları içerir.
* Çekilen verileri opsiyonel olarak Excel dosyası olarak kaydedebilirsiniz.

## Kurulum

Kütüphaneyi kullanmak için aşağıdaki adımları izleyin:

1. Python'ı sisteminize yükleyin: https://www.python.org/downloads/
2. Terminali açın ve paketi yüklemek için aşağıdaki komutu çalıştırın:

```bash
pip install bddkdata
```

Spesifik bir versiyona ait kurulum yapacaksanız aşağıdaki örnekte olduğu gibi komutu çalıştırabilirsiniz.

```bash
pip install bddkdata==0.1.0
```

Yüklü paketin versiyonuna aşağıdaki komut yardımıyla ulaşabilirsiniz.

```bash
pip show bddkdata
```

## Fonksiyonlar

### `fetch_data`

BDDK API'dan tablo verisi çeker.

Parametreler:

* `start_year` (int): Başlangıç yılı (YYYY)
* `start_month` (int): Başlangıç ayı (1-12)
* `end_year` (int): Bitiş yılı (YYYY)
* `end_month` (int): Bitiş ayı (1-12)
* `table_no` (int): Tablo numarası (örn: 1)
* `currency` (str): "TL" veya "USD"
* `group` (int): Grup ID'si (örn: 10001)
* `lang` (str): "tr" veya "en" (varsayılan "tr")
* `save_excel` (bool, opsiyonel): True verilirse sonuç Excel dosyasına kaydedilir. Varsayılan olarak False'tur.

Dönüş:

* `pandas.DataFrame` (veya veri yoksa `None`)

### `get_tables`

Mevcut tablo listesini döndürür.

Parametreler:

* `lang` (str): "tr" veya "en" (varsayılan "tr")

Dönüş:

* `pandas.DataFrame`

### `get_groups`

Mevcut grup listesini döndürür.

Parametreler:

* `lang` (str): "tr" veya "en" (varsayılan "tr")

Dönüş:

* `pandas.DataFrame`

## Örnek

```python
from bddkdata import fetch_data, get_tables, get_groups

print(get_tables(lang="tr"))
print(get_groups(lang="tr"))

df = fetch_data(
    start_year=2024,
    start_month=1,
    end_year=2025,
    end_month=5,
    table_no=1,
    currency="TL",
    group=10001,
    lang="tr",
    save_excel=True
)
print(df)
```

## Notlar

* Kütüphane, BDDK'nın web sitesindeki verilere bağımlıdır. Bu nedenle, verilerin doğruluğu ve sürekliliği için lütfen ilgili web sitesini kontrol edin: [BDDK](https://www.bddk.org.tr/BultenAylik/tr/)
* Kütüphanenin geliştirilmesi ve iyileştirilmesi için geri bildirimlerinizi bekliyorum. GitHub reposuna katkıda bulunun: [GitHub Repo](https://github.com/urazakgul/bddkdata)
* Herhangi bir sorun veya öneride lütfen GitHub reposundaki "Issue" bölümünden yeni bir konu açarak bildirim sağlayın: [GitHub Issues](https://github.com/urazakgul/bddkdata/issues)

## Sürüm Notları

### v0.1.0 - 19/07/2025

* İlk sürüm yayınlandı.

## Lisans

Bu proje MIT Lisansı altında lisanslanmıştır.

## For those who prefer English:

## Description

`bddkdata` is a Python package that enables you to fetch financial tables and banking sector data published on the official website of the Banking Regulation and Supervision Agency (BRSA, BDDK) of Turkey. The library provides fast and flexible access to monthly updated core banking indicators, making your data analysis and reporting processes easier. Data is fetched directly from the BRSA's open data service and delivered in ready-to-use pandas DataFrame format with both Turkish and English column labels.

## Features

* Easily fetch monthly tables published by the BRSA for any desired date range.
* Fetch data with Turkish/English column support for all tables and groups.
* Simple to use; outputs are returned directly as `pandas.DataFrame`.
* Errors and messages are displayed in Turkish or English.
* Includes helper functions for listing available tables and group names.
* Optionally save fetched data as an Excel file.

## Installation

To use the package, follow these steps:

1. Install Python on your system: https://www.python.org/downloads/
2. Open a terminal and install the package with:

```bash
pip install bddkdata
```

To install a specific version, use:

```bash
pip install bddkdata==0.1.0
```

To check the installed version:

```bash
pip show bddkdata
```

## Functions

### `fetch_data`

Fetches table data from the BRSA API.

Parameters:

* `start_year` (int): Starting year (YYYY)
* `start_month` (int): Starting month (1–12)
* `end_year` (int): Ending year (YYYY)
* `end_month` (int): Ending month (1–12)
* `table_no` (int): Table number (e.g., 1)
* `currency` (str): "TL" or "USD"
* `group` (int): Group ID (e.g., 10001)
* `lang` (str): "tr" or "en" (default "tr")
* `save_excel` (bool, optional): If True, saves the result to an Excel file. Defaults to False.

Returns:

* `pandas.DataFrame` (or `None` if no data is available)

### `get_tables`

Fetches the list of available tables.

Parameters:

* `lang` (str): "tr" or "en" (default "tr")

Returns:

* `pandas.DataFrame`

### `get_groups`

Fetches the list of available groups.

Parameters:

* `lang` (str): "tr" or "en" (default "tr")

Returns:

* `pandas.DataFrame`

## Example

```python
from bddkdata import fetch_data, get_tables, get_groups

print(get_tables(lang="en"))
print(get_groups(lang="en"))

df = fetch_data(
    start_year=2024,
    start_month=1,
    end_year=2025,
    end_month=5,
    table_no=1,
    currency="USD",
    group=10001,
    lang="en",
    save_excel=True
)
print(df)
```

## Notes

* The package depends on data from the official BRSA website. Please check the website for data accuracy and availability: [BRSA](https://www.bddk.org.tr/BultenAylik/en/)
* I welcome your feedback to improve and develop this library. You can contribute on GitHub: [GitHub Repo](https://github.com/urazakgul/bddkdata)
* For any issues or suggestions, please open a new topic in the "Issue" section of the GitHub repository: [GitHub Issues](https://github.com/urazakgul/bddkdata/issues)

## Release Notes

### v0.1.0 - 19/07/2025

* First release published.

## License

This project is licensed under the MIT License.