tcmb

tcmb is a Python API wrapper around the Central Bank of the Republic of Türkiye (TCMB) Web Service. It is an unofficial open-source Python package intended for personal use (Disclaimer).

tcmb, Türkiye Cumhuriyeti Merkez Bankası (TCMB) Web Servisi'ne Python aracılığıyla erişimi sağlayan resmi olmayan API uygulamasıdır. Kişisel kullanım ve araştırma maksadıyla hazırlanmıştır (Elektronik Veri Dağıtım Sistemi (EVDS) Kullanım Koşulları).

Quickstart

shell pip install tcmb

```python import tcmb

client = tcmb.Client(api_key="...")

data = client.read(series="TP.DK.USD.S.YTL") ```

Overview

Data Hierarchy

1. Categories:

Categories are at the top level of the TCMB data hierarchy.

```python client = tcmb.Client(api_key="...")

show categories

Client.categories

{'CATEGORYID': 1.0, 'TOPICTITLEENG': 'MARKET STATISTICS', 'TOPICTITLE_TR': 'PİYASA VERİLERİ'} ```

It is also possible to get the same information using the client.get_categories_metadata() method.

1. Data Groups:

Each category consists of a number of data groups.

```python client = tcmb.Client(api_key="...")

show data groups

Client.datagroups

[{'DATAGROUPCODE': 'biepyrepo', 'CATEGORYID': 1, 'DATAGROUPNAME': 'Açık Piyasa Repo ve Ters Repo İşlemleri', 'DATAGROUPNAMEENG': 'Open Market Repo and Reverse Repo Transactions', ...} {'DATAGROUPCODE': 'biemkbral', 'CATEGORYID': 0, 'DATAGROUPNAME': 'Altın Borsası İşlemleri-İstanbul (TL-ABD Doları)(Arşiv)', 'DATAGROUPNAMEENG': 'Istanbul Gold Exchange (TRY-USD)(Archive)', ...}] ```

It is also possible to filter the datagroups metadata using the client.get_datagroups_metadata() method.

1. Series

Datagroups consist of time series, each having a series key such as TP.YSSK.A1 or TP.DK.USD.S.YTL. Series is read using the .read() method.

```python import tcmb

client = tcmb.Client(api_key="...")

read one time series

data = client.read("TP.YSSK.A1")

read multiple time series

data = client.read(["TP.YSSK.A1", "TP.YSSK.A2", "TP.YSSK.A3"]) ```

A convenient way to read time series without initializing the Client instance is using the read() function in the core.py module.

```python import tcmb

read one time series

data = tcmb.read("TP.YSSK.A1", api_key="...")

read multiple time series

data = tcmb.read(["TP.YSSK.A1", "TP.YSSK.A2", "TP.YSSK.A3"], api_key="...") ```

Series metadata can be fetched with .get_series_metadata() method.

```python

show metadata of each series within a data group

client.getseriesmetadata(datagroup="bie_yssk")

[{'SERIECODE': 'TP.YSSK.A1', 'DATAGROUPCODE': 'bieyssk', 'SERIENAME': '1-2 Yıl(ABD doları)', 'SERIENAMEENG': '1-2 Years(USD)', ...}, {'SERIECODE': 'TP.YSSK.A2', 'DATAGROUPCODE': 'bieyssk', 'SERIENAME': '3 Yıl(ABD doları)', 'SERIENAMEENG': '3 Years(USD)', ...}]

show metadata of a specific time series

client.getseriesmetadata(series="TP.YSSK.A1")

[{'SERIECODE': 'TP.YSSK.A1', 'DATAGROUPCODE': 'bieyssk', 'SERIENAME': '1-2 Yıl(ABD doları)', 'SERIENAMEENG': '1-2 Years(USD)', ...}] ```

Wildcard Characters

The wildcard characters are represented as an asterisk * or a question mark ?. The asterisk * represents any number of characters, while the question mark ? represents a single character. Additionally, omitting the value has the same effect as using an asterisk. Note that, wildcard character option is not a feature of TCMB web service. Wildcard pattern search is implemented within the tcmb package and depends on the package data.

```python

data = tcmb.read("TP.DK.USD.*.YTL") print(data.columns)

Index(['TPDKUSDAYTL', 'TPDKUSDSYTL', 'TPDKUSDCYTL', 'TPDKUSDAEFYTL', 'TPDKUSDSEFYTL'], dtype='object') ```

Installation

sh pip install tcmb

Authentication

An API key is required to access the Web Service. Users can sign up from the login page. Once logged in, API Key is generated from the Profile page.

There are two ways of providing API key to the tcmb client. - Using environment variables:

shell $ export TCMB_API_KEY="..."

python import os os.environ["TCMB_API_KEY"] = "..."

• Passing api_key when initializing the Client class.

python client = Client(api_key="...")

Disclaimer

tcmb is an unofficial open-source package intended for personal use and research purposes. Please see TCMB's EVDS Disclaimer for the official terms of use of the EVDS Web Service.