cbrapi 0.1.0__tar.gz

cbrapi-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.3
+Name: cbrapi
+Version: 0.1.0
+Summary: Python interface for Central Bank of Russia (CBR) API
+Author: AAARRRT
+Author-email: artiomsalazov@gmail.com
+Requires-Python: >=3.10,<4.0.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: lxml
+Requires-Dist: pandas (>=2.3.2,<3.0.0)
+Requires-Dist: requests
+Requires-Dist: suds-py3
+Description-Content-Type: text/markdown
+
+
+[![Python](https://img.shields.io/badge/python-v3-brightgreen.svg)](https://www.python.org/)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/okama.svg)](https://pypi.org/project/okama/)
+[![License](https://img.shields.io/pypi/l/okama.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://static.pepy.tech/badge/cbr-api-client)](https://pepy.tech/project/cbr-api)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# CBRAPI
+
+`cbrapi` is a Python client for the Central Bank of Russia's web services.
+
+## Table of contents
+
+- [CBR-API main features](#cbr-api-main-features)
+- [Core Functions](#core-functions)
+  - [CURRENCY](#currency)
+  - [METALS](#metals)
+  - [RATES](#rates)
+  - [RESERVES](#reserves)
+  - [RUONIA](#ruonia)
+- [Getting started](#getting-started)
+- [License](#license)
+
+## CBRAPI main features
+This client provides structured access to the following key data categories from the CBR:  
+- CURRENCY: Official exchange rates of foreign currencies against the Russian Ruble.
+- METALS: Official prices of precious metals.
+- RATES: Key interest rates and interbank lending rates. 
+- RESERVES: Data on international reserves and foreign currency liquidity.
+- RUONIA: The Russian Overnight Index Average and related benchmark rates.
+
+## Core Functions
+
+### CURRENCY
+
+#### Get a list of available currencies
+Returns a list of all available currency tickers supported by the API.  
+`get_currencies_list()`  
+
+#### Get an internal CBR currency code for a ticker
+Retrieves the internal CBR currency code for a given currency ticker.  
+`get_currency_code(ticker: str)`  
+
+#### Get currency rate historical data
+Fetches historical exchange rate data for a specified currency and date range.  
+`get_time_series(symbol: str, first_date: str, last_date: str, period: str = 'D')`  
+
+### METALS
+
+#### Get precious metals prices time series
+Provides historical prices for precious metals (Gold, Silver, Platinum, Palladium).  
+`get_metals_prices(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+### RATES
+
+IBOR: Interbank Offered Rate.  
+
+#### Get the key rate time series
+Retrieves the historical key rate set by the Central Bank of Russia.  
+`get_key_rate(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get Interbank Offered Rate and related interbank rates
+Fetches the historical Interbank Offered Rate and related interbank rates.  
+`get_ibor(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'M')`  
+
+### RESERVES
+
+MRRF: International Reserves and Foreign Currency Liquidity.  
+
+#### Get International Reserves and Foreign Currency Liquidity data
+Provides time series data for International Reserves and Foreign Currency Liquidity.
+`get_mrrf(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'M')`  
+
+### RUONIA
+
+RUONIA: Russian Overnight Index Average.  
+ROISfix: Russian Overnight Index Swap Fixing.  
+
+#### Get RUONIA time series data
+Retrieves RUONIA time series data for a specific symbol.  
+`get_ruonia_ts(symbol: str, first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get RUONIA index and averages time series
+Fetches the historical RUONIA index and averages.  
+`get_ruonia_index(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get RUONIA overnight value time series
+Provides the historical RUONIA overnight value.  
+`get_ruonia_overnight(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get ROISfix time series
+Retrieves the historical ROISfix time series data.  
+`get_roisfix(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+## Installation
+
+```bash
+pip install cbrapi
+```
+
+The latest development version can be installed directly from GitHub:
+
+```bash
+git clone https://github.com/mbk-dev/cbrapi.git
+cd cbrapi
+poetry install
+```
+
+## Getting started
+
+
+### 1. Get USD/RUB exchange rate with historical data
+
+```python
+import cbrapi as cbr
+
+usd_rub = cbr.get_currency_rate('USDRUB.CBR', '2024-01-01', '2024-12-31')
+print(usd_rub)
+```
+![](../images/images/readme1.jpg?raw=true) 
+
+
+### 2. Monitor Central Bank's key rate monthly changes
+
+```python
+key_rate = cbr.get_key_rate('2020-01-01', '2024-12-31', period='M')
+print(key_rate)
+```
+![](../images/images/readme2.jpg?raw=true) 
+
+
+### 3. Track precious metals market trends
+```python
+metals = cbr.get_metals_prices('2024-01-01', '2025-01-31')
+print(metals)
+```
+![](../images/images/readme3.jpg?raw=true) 
+
+
+### 4. Analyze international reserves data
+```python
+reserves = cbr.get_mrrf('2023-01-01', '2024-12-31')
+print(reserves)
+```
+![](../images/images/readme4.jpg?raw=true) 
+
+
+## License
+
+MIT
+

cbrapi-0.1.0/README.md

@@ -0,0 +1,150 @@
+
+[![Python](https://img.shields.io/badge/python-v3-brightgreen.svg)](https://www.python.org/)
+[![PyPI Latest Release](https://img.shields.io/pypi/v/okama.svg)](https://pypi.org/project/okama/)
+[![License](https://img.shields.io/pypi/l/okama.svg)](https://opensource.org/licenses/MIT)
+[![Downloads](https://static.pepy.tech/badge/cbr-api-client)](https://pepy.tech/project/cbr-api)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
+
+# CBRAPI
+
+`cbrapi` is a Python client for the Central Bank of Russia's web services.
+
+## Table of contents
+
+- [CBR-API main features](#cbr-api-main-features)
+- [Core Functions](#core-functions)
+  - [CURRENCY](#currency)
+  - [METALS](#metals)
+  - [RATES](#rates)
+  - [RESERVES](#reserves)
+  - [RUONIA](#ruonia)
+- [Getting started](#getting-started)
+- [License](#license)
+
+## CBRAPI main features
+This client provides structured access to the following key data categories from the CBR:  
+- CURRENCY: Official exchange rates of foreign currencies against the Russian Ruble.
+- METALS: Official prices of precious metals.
+- RATES: Key interest rates and interbank lending rates. 
+- RESERVES: Data on international reserves and foreign currency liquidity.
+- RUONIA: The Russian Overnight Index Average and related benchmark rates.
+
+## Core Functions
+
+### CURRENCY
+
+#### Get a list of available currencies
+Returns a list of all available currency tickers supported by the API.  
+`get_currencies_list()`  
+
+#### Get an internal CBR currency code for a ticker
+Retrieves the internal CBR currency code for a given currency ticker.  
+`get_currency_code(ticker: str)`  
+
+#### Get currency rate historical data
+Fetches historical exchange rate data for a specified currency and date range.  
+`get_time_series(symbol: str, first_date: str, last_date: str, period: str = 'D')`  
+
+### METALS
+
+#### Get precious metals prices time series
+Provides historical prices for precious metals (Gold, Silver, Platinum, Palladium).  
+`get_metals_prices(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+### RATES
+
+IBOR: Interbank Offered Rate.  
+
+#### Get the key rate time series
+Retrieves the historical key rate set by the Central Bank of Russia.  
+`get_key_rate(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get Interbank Offered Rate and related interbank rates
+Fetches the historical Interbank Offered Rate and related interbank rates.  
+`get_ibor(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'M')`  
+
+### RESERVES
+
+MRRF: International Reserves and Foreign Currency Liquidity.  
+
+#### Get International Reserves and Foreign Currency Liquidity data
+Provides time series data for International Reserves and Foreign Currency Liquidity.
+`get_mrrf(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'M')`  
+
+### RUONIA
+
+RUONIA: Russian Overnight Index Average.  
+ROISfix: Russian Overnight Index Swap Fixing.  
+
+#### Get RUONIA time series data
+Retrieves RUONIA time series data for a specific symbol.  
+`get_ruonia_ts(symbol: str, first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get RUONIA index and averages time series
+Fetches the historical RUONIA index and averages.  
+`get_ruonia_index(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get RUONIA overnight value time series
+Provides the historical RUONIA overnight value.  
+`get_ruonia_overnight(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+#### Get ROISfix time series
+Retrieves the historical ROISfix time series data.  
+`get_roisfix(first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = 'D')`  
+
+## Installation
+
+```bash
+pip install cbrapi
+```
+
+The latest development version can be installed directly from GitHub:
+
+```bash
+git clone https://github.com/mbk-dev/cbrapi.git
+cd cbrapi
+poetry install
+```
+
+## Getting started
+
+
+### 1. Get USD/RUB exchange rate with historical data
+
+```python
+import cbrapi as cbr
+
+usd_rub = cbr.get_currency_rate('USDRUB.CBR', '2024-01-01', '2024-12-31')
+print(usd_rub)
+```
+![](../images/images/readme1.jpg?raw=true) 
+
+
+### 2. Monitor Central Bank's key rate monthly changes
+
+```python
+key_rate = cbr.get_key_rate('2020-01-01', '2024-12-31', period='M')
+print(key_rate)
+```
+![](../images/images/readme2.jpg?raw=true) 
+
+
+### 3. Track precious metals market trends
+```python
+metals = cbr.get_metals_prices('2024-01-01', '2025-01-31')
+print(metals)
+```
+![](../images/images/readme3.jpg?raw=true) 
+
+
+### 4. Analyze international reserves data
+```python
+reserves = cbr.get_mrrf('2023-01-01', '2024-12-31')
+print(reserves)
+```
+![](../images/images/readme4.jpg?raw=true) 
+
+
+## License
+
+MIT

cbrapi-0.1.0/cbrapi/__init__.py

@@ -0,0 +1,23 @@
+from importlib.metadata import version
+
+
+from cbrapi.cbr_settings import make_cbr_client
+from cbrapi.currency import get_currencies_list, get_currency_code, get_time_series
+from cbrapi.helpers import (
+    pad_missing_periods,
+    calculate_inverse_rate,
+    normalize_data,
+    guess_date,
+)
+from cbrapi.ruonia import (
+    get_ruonia_ts,
+    get_ruonia_index,
+    get_ruonia_overnight,
+    get_roisfix,
+)
+from cbrapi.rates import get_key_rate, get_ibor
+from cbrapi.metals import get_metals_prices
+from cbrapi.reserves import get_mrrf
+
+
+# __version__ = version("cbr")

cbrapi-0.1.0/cbrapi/cbr_settings.py

@@ -0,0 +1,15 @@
+from suds.client import Client
+from suds.xsd.doctor import Import, ImportDoctor
+
+
+def make_cbr_client():
+    global cbr_client
+    imp = Import("http://www.w3.org/2001/XMLSchema")  # the schema to import
+    imp.filter.add("http://web.cbr.ru/")  # the schema to import into
+    d = ImportDoctor(imp)
+    return Client(
+        "http://www.cbr.ru/DailyInfoWebServ/DailyInfo.asmx?wsdl",
+        doctor=d,
+        retxml=True,
+        headers={"User-Agent": "Mozilla"},
+    )

cbrapi-0.1.0/cbrapi/currency.py

@@ -0,0 +1,177 @@
+import re
+from datetime import datetime, date
+from typing import Optional
+
+import pandas as pd
+
+from cbrapi.cbr_settings import make_cbr_client
+from cbrapi.helpers import (
+    normalize_data,
+    guess_date,
+    pad_missing_periods,
+    calculate_inverse_rate,
+)
+
+
+today = date.today()
+
+
+def get_currencies_list() -> pd.DataFrame:
+    """
+    Get a list of available currencies from CBR.
+
+    Returns
+    -------
+    pd.DataFrame
+        Combined dataframe with all available currencies for daily and monthly frequencies.
+        Contains currency codes, character codes, names, and metadata.
+
+    Notes
+    -----
+    The function retrieves two separate lists:
+    - Currencies with DAILY time series data
+    - Currencies with MONTHLY time series data
+    Returns a combined dataframe with all available currencies.
+
+    Examples
+    --------
+    >>> get_currencies_list()
+    """
+    cbr_client = make_cbr_client()
+    # get currency table with DAILY time series
+    currencies_daily_xml = cbr_client.service.EnumValutesXML(False)
+    df_daily = pd.read_xml(currencies_daily_xml, xpath="//EnumValutes")
+
+    # get currency table with MONTHLY time series
+    currencies_monthly_xml = cbr_client.service.EnumValutesXML(True)
+    df_monthly = pd.read_xml(currencies_monthly_xml, xpath="//EnumValutes")
+    return pd.concat([df_daily, df_monthly], axis=0, join="outer", copy="false")
+
+
+def get_currency_code(ticker: str) -> str:
+    """
+    Return an internal CBR currency code for a ticker.
+
+    Parameters
+    ----------
+    ticker : str
+        Currency ticker in format 'CCY1CCY2.CBR' (e.g., 'USDRUB.CBR')
+
+    Returns
+    -------
+    str
+        Internal CBR currency code (e.g., 'R01235')
+
+    Raises
+    ------
+    ValueError
+        If the currency ticker is not found in the CBR database.
+
+    Notes
+    -----
+    Handles cases where multiple currency codes might exist for the same ticker
+    by selecting the first available option.
+
+    Examples
+    --------
+    >>> get_currency_code('USDRUB.CBR')
+    'R01235'
+    """
+    cbr_symbol = ticker[:3]
+    currencies_list = get_currencies_list()
+    # Some tickers has 2 Vcode in CBR database. ILS - "Израильский шекель" and "Новый израильский шекель"
+    # First row is taken with .iloc
+    row = (
+        currencies_list[currencies_list["VcharCode"] == cbr_symbol].iloc[0, :].squeeze()
+    )
+    try:
+        code = row.loc["Vcode"]
+    except KeyError as e:
+        raise ValueError(f"There is no {ticker} in CBR database.") from e
+    return code
+
+
+def get_time_series(
+    symbol: str, first_date: str, last_date: str, period: str = "D"
+) -> pd.Series:
+    """
+    Get currency rate historical data from CBR.
+
+    Parameters
+    ----------
+    symbol : str
+        Currency pair symbol in format 'CCY1CCY2.CBR' (e.g., 'USDRUB.CBR')
+    first_date : str
+        Start date in format 'YYYY-MM-DD' or 'YYYY-MM'
+    last_date : str
+        End date in format 'YYYY-MM-DD' or 'YYYY-MM'
+    period : {'D', 'M'}, default 'D'
+        Data frequency: 'D' for daily, 'M' for monthly
+
+    Returns
+    -------
+    pd.Series
+        Time series of currency exchange rates with datetime index.
+
+    Raises
+    ------
+    ValueError
+        If the CBR data format has changed unexpectedly.
+        If date format is invalid.
+        If currency symbol is not found.
+
+    Notes
+    -----
+    - Supports both direct and inverse rate calculations
+    - Handles data normalization and missing period padding
+    - Performs resampling for different frequencies
+    - Some tickers may return empty data if not available
+
+    Examples
+    --------
+    >>> get_time_series('USDRUB.CBR', '2023-01-01', '2023-12-31', 'D')
+    >>> get_time_series('EURUSD.CBR', '2023-01', '2023-12', 'M')
+    """
+    try:
+        data1 = datetime.strptime(first_date, "%Y-%m-%d")
+        data2 = datetime.strptime(last_date, "%Y-%m-%d")
+    except ValueError:
+        data1 = datetime.strptime(first_date, "%Y-%m")
+        data2 = datetime.strptime(last_date, "%Y-%m")
+    symbol = symbol.upper()
+    if re.match("RUB", symbol):
+        foreign_ccy = re.search(r"^RUB(.*).CBR$", symbol)[1]
+        query_symbol = foreign_ccy + "RUB.CBR"
+        method = "inverse"
+    else:
+        query_symbol = symbol
+        method = "direct"
+    code = get_currency_code(query_symbol)
+    cbr_client = make_cbr_client()
+    rate_xml = cbr_client.service.GetCursDynamic(data1, data2, code)
+    try:
+        df = pd.read_xml(rate_xml, xpath="//ValuteCursDynamic")
+    except ValueError:
+        return pd.Series()
+    cbr_cols1 = {"rowOrder", "id", "Vnom", "Vcode", "CursDate", "Vcurs"}
+    cbr_cols2 = cbr_cols1.union({"VunitRate"})
+    if set(df.columns) not in [cbr_cols1, cbr_cols2]:
+        raise ValueError(
+            "CBR data has different columns. Probably data format is changed."
+        )
+    df.drop(columns=["id", "rowOrder", "Vcode"], inplace=True)
+    if "VunitRate" in list(df.columns):
+        df.drop(columns=["VunitRate"], inplace=True)
+    df["Vcurs"] /= df["Vnom"]
+    df.drop(columns=["Vnom"], inplace=True)
+    df = df.astype({"CursDate": "period[D]"}, copy=False)
+    df = df.astype({"Vcurs": "float"}, copy=False)
+    df.set_index("CursDate", inplace=True, verify_integrity=True)
+    df.sort_index(ascending=True, inplace=True)
+    s = df.squeeze(axis=1)  # all outputs must be pd.Series
+    s = pad_missing_periods(s, freq="D")
+    s.index.rename("date", inplace=True)
+    if period.upper() == "M":
+        s = s.resample("M").last()
+    s = calculate_inverse_rate(s) if method == "inverse" else s
+    return s.rename(symbol)

cbrapi-0.1.0/cbrapi/helpers.py

@@ -0,0 +1,147 @@
+from typing import Union
+from datetime import datetime, date
+import pandas as pd
+
+
+def pad_missing_periods(
+    ts: Union[pd.Series, pd.DataFrame], freq: str = "D"
+) -> Union[pd.Series, pd.DataFrame]:
+    """
+    Pad missing dates and values in the time series.
+    """
+    name = ts.index.name
+    if not isinstance(ts.index, pd.PeriodIndex):
+        ts.index = ts.index.to_period(freq)
+    ts.sort_index(
+        ascending=True, inplace=True
+    )  # The order should be ascending to make new Period index
+    idx = pd.period_range(start=ts.index[0], end=ts.index[-1], freq=freq)
+    ts = ts.reindex(idx, method="pad")
+    ts.index.rename(name, inplace=True)
+    return ts
+
+
+def calculate_inverse_rate(close_ts):
+    """
+    Inverse close values for currency rate data.
+    """
+    return 1.0 / close_ts
+
+
+def set_datetime_index(data):
+    """
+    Set datetime index for DataFrame by detecting date columns.
+    """
+    if not isinstance(data.index, pd.DatetimeIndex):
+        for col in data.columns:
+            if any(keyword in str(col) for keyword in ["CDate", "DateMet", "D0", "DT"]):
+                data[col].str.split("T").str[0]
+                data.index = pd.DatetimeIndex(
+                    pd.to_datetime(data[col], utc=True)
+                ).tz_convert(None)
+                data.index.name = "DATE"
+                data.drop(col, axis=1, inplace=True)
+                break
+    return data
+
+
+def remove_unnecessary_columns(data):
+    """
+    Remove unnecessary columns from DataFrame.
+    """
+    data.drop(
+        columns=[
+            col
+            for col in ["id", "rowOrder", "vol", "DateUpdate"]
+            if col in data.columns
+        ],
+        inplace=True,
+    )
+    return data
+
+
+def unstack_groups(data, symbol):
+    """
+    Unstack grouped data based on symbol type.
+    """
+    if symbol == "DrgMet":
+        data = data.groupby([data.index, "CodMet"])["price"].first().unstack()
+        data.columns.name = None
+
+    if symbol == "MKR":
+        data = (
+            data.groupby([data.index, "p1"])[["d1", "d7", "d30", "d90", "d180", "d360"]]
+            .first()
+            .unstack(level="p1")
+        )
+        data.columns = data.columns.rename(None, level=1)
+        data.columns.name = None
+
+    return data
+
+
+def column_rename(data, level_0, level_1):
+    """
+    Rename columns based on mapping dictionaries.
+    """
+    if isinstance(data.columns, pd.MultiIndex):
+        if level_0:
+            new_level_0 = data.columns.levels[0].map(lambda x: level_0.get(str(x), x))
+            data.columns = data.columns.set_levels(new_level_0, level=0)
+
+        if level_1:
+            new_level_1 = data.columns.levels[1].map(lambda x: level_1.get(str(x), x))
+            data.columns = data.columns.set_levels(new_level_1, level=1)
+
+    else:
+        if level_1 and isinstance(level_1, dict):
+            data = data.rename(columns=level_1)
+            available_columns = [col for col in level_1.values() if col in data.columns]
+            data = data[available_columns] if available_columns else data
+
+        else:
+            if level_1 and not isinstance(level_1, dict):
+                if len(data.columns) == 1:
+                    data = data.rename(columns={data.columns[0]: str(level_1)})
+    return data
+
+
+def normalize_data(data, period, level_0=None, level_1=None, symbol=None):
+    """
+    Normalize time series data through multiple processing steps.
+    """
+    if isinstance(data, pd.Series):
+        data = data.to_frame()
+
+    set_datetime_index(data)
+
+    remove_unnecessary_columns(data)
+
+    data = unstack_groups(data, symbol)
+
+    data = column_rename(data, level_0, level_1)
+
+    data = pad_missing_periods(data)
+
+    if period.upper() == "M":
+        data = data.resample("M").last()
+
+    if len(data.columns) == 1:
+        data = data.squeeze()
+
+    return data
+
+
+def guess_date(input_date, default_value):
+    """
+    Create data in datetime format.
+    CBR accepts "%Y-%m-%d" format only.
+    """
+    if input_date:
+        try:
+            date = datetime.strptime(input_date, "%Y-%m-%d")
+        except ValueError:
+            date = datetime.strptime(input_date, "%Y-%m")
+    else:
+        date = datetime.strptime(default_value, "%Y-%m-%d")
+    return date

cbrapi-0.1.0/cbrapi/metals.py

@@ -0,0 +1,71 @@
+from datetime import datetime, date
+from typing import Optional
+
+import pandas as pd
+
+from cbrapi.cbr_settings import make_cbr_client
+from cbrapi.helpers import normalize_data, guess_date
+
+
+today = date.today()
+
+
+def get_metals_prices(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "D"
+) -> pd.DataFrame:
+    """
+    Get precious metals prices time series from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '1999-10-01'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'D'}, default 'D'
+        Data periodicity. Currently only daily ('D') frequency is supported.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with datetime index and the following columns:
+        - GOLD : Gold price (RUB per gram)
+        - SILVER : Silver price (RUB per gram)
+        - PLATINUM : Platinum price (RUB per gram)
+        - PALLADIUM : Palladium price (RUB per gram)
+
+    Notes
+    -----
+    Prices are provided in Russian Rubles per gram.
+    Data is available from October 1999.
+
+    Examples
+    --------
+    >>> get_metals_prices('2023-01-01', '2023-12-31')
+    >>> get_metals_prices(period='M')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="1999-10-01")
+    data2 = guess_date(last_date, default_value=str(today))
+    metals_xml = cbr_client.service.DragMetDynamic(data1, data2)
+
+    try:
+        df = pd.read_xml(metals_xml, xpath=".//DrgMet")
+    except ValueError:
+        return pd.Series()
+
+    level_1_column_mapping = {
+        1: "GOLD",
+        2: "SILVER",
+        3: "PLATINUM",
+        4: "PALLADIUM",
+    }
+
+    df = normalize_data(
+        data=df, period=period, symbol="DrgMet", level_1=level_1_column_mapping
+    )
+    return df

cbrapi-0.1.0/cbrapi/rates.py

@@ -0,0 +1,171 @@
+from datetime import datetime, date
+from typing import Optional
+
+import pandas as pd
+
+from cbrapi.cbr_settings import make_cbr_client
+from cbrapi.helpers import normalize_data, guess_date
+
+
+today = date.today()
+
+
+def get_key_rate(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "D"
+) -> pd.Series:
+    """
+    Get the key rate time series from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '2013-09-13'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'D'}, default 'D'
+        Data periodicity. Currently only daily ('D') frequency is supported.
+
+    Returns
+    -------
+    pd.Series
+        Time series of key rate values with datetime index.
+        Rates are returned as decimals (e.g., 0.075 for 7.5%).
+
+    Notes
+    -----
+    The key rate is the main instrument of the Bank of Russia's monetary policy.
+    It influences interest rates in the economy and is used for liquidity provision
+    and absorption operations.
+
+    Examples
+    --------
+    >>> get_key_rate('2023-01-01', '2023-12-31')
+    >>> get_key_rate(period='D')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="2013-09-13")
+    data2 = guess_date(last_date, default_value=str(today))
+    key_rate_xml = cbr_client.service.KeyRate(data1, data2)
+
+    try:
+        df = pd.read_xml(key_rate_xml, xpath=".//KR")
+    except ValueError:
+        return pd.Series()
+
+    level_1_column_mapping = {"Rate": "KEY_RATE"}
+
+    df = normalize_data(
+        data=df, period=period, symbol="KEY_RATE", level_1=level_1_column_mapping
+    )
+    return df
+
+
+def get_ibor(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "M"
+) -> pd.DataFrame:
+    """
+    Get Interbank Offered Rate and related interbank rates from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '2013-09-13'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'M'}, default 'M'
+        Data periodicity. Currently only monthly ('M') frequency is supported.
+
+    Returns
+    -------
+    pd.DataFrame
+        Multi-level DataFrame with datetime index containing interbank rates.
+        First level columns represent tenors, second level represents rate types:
+
+        Available loan terms:
+        - D1 : 1 day
+        - D7 : 7 days
+        - D30 : 30 days
+        - D180 : 180 days
+        - D360 : 360 days
+
+        Rate types include:
+        - MIBID_RUB : Moscow Interbank Bid Rate (RUB)
+        - MIBOR_RUB : Moscow Interbank Offered Rate (RUB)
+        - MIACR_RUB : Moscow Interbank Actual Credit Rate (RUB)
+        - MIACR_IG_RUB : MIACR for investment grade (RUB)
+        - MIACR_RUB_TURNOVER : MIACR turnover (RUB)
+        - MIACR_IG_RUB_TURNOVER : MIACR IG turnover (RUB)
+        - MIACR_B_RUB : MIACR for banks (RUB)
+        - MIACR_B_RUB_TURNOVER : MIACR banks turnover (RUB)
+        - MIBID_USD : Moscow Interbank Bid Rate (USD)
+        - MIBOR_USD : Moscow Interbank Offered Rate (USD)
+        - MIACR_USD : Moscow Interbank Actual Credit Rate (USD)
+        - MIACR_IG_USD : MIACR for investment grade (USD)
+        - MIACR_USD_TURNOVER : MIACR turnover (USD)
+        - MIACR_IG_USD_TURNOVER : MIACR IG turnover (USD)
+        - MIACR_B_USD : MIACR for banks (USD)
+        - MIACR_B_USD_TURNOVER : MIACR banks turnover (USD)
+
+    Notes
+    -----
+    All rates are returned as decimals (e.g., 0.05 for 5%).
+    Turnover values represent trading volumes.
+
+    Examples
+    --------
+    >>> get_ibor('2023-01-01', '2023-12-31')
+    >>> get_ibor(period='M')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="2013-09-13")
+    data2 = guess_date(last_date, default_value=str(today))
+    mkr_xml = cbr_client.service.MKR(data1, data2)
+
+    try:
+        df = pd.read_xml(mkr_xml, xpath=".//MKR")
+    except ValueError:
+        return pd.Series()
+
+    level_0_column_mapping = {
+        "d1": "D1",
+        "d7": "D7",
+        "d30": "D30",
+        "d180": "D180",
+        "d360": "D360",
+    }
+
+    level_1_column_mapping = {
+        "1": "MIBID_RUB",
+        "2": "MIBOR_RUB",
+        "3": "MIACR_RUB",
+        "4": "MIACR_IG_RUB",
+        "5": "MIACR_RUB_TURNOVER",
+        "6": "MIACR_IG_RUB_TURNOVER",
+        "7": "MIACR_B_RUB",
+        "8": "MIACR_B_RUB_TURNOVER",
+        "9": "MIBID_USD",
+        "10": "MIBOR_USD",
+        "11": "MIACR_USD",
+        "12": "MIACR_IG_USD",
+        "13": "MIACR_USD_TURNOVER",
+        "14": "MIACR_IG_USD_TURNOVER",
+        "15": "MIACR_B_USD",
+        "16": "MIACR_B_USD_TURNOVER",
+    }
+
+    df = normalize_data(
+        data=df,
+        period=period,
+        symbol="MKR",
+        level_0=level_0_column_mapping,
+        level_1=level_1_column_mapping,
+    )
+    return df

cbrapi-0.1.0/cbrapi/reserves.py

@@ -0,0 +1,81 @@
+from datetime import datetime, date
+from typing import Optional
+
+import pandas as pd
+
+from cbrapi.cbr_settings import make_cbr_client
+from cbrapi.helpers import normalize_data, guess_date
+
+
+today = date.today()
+
+
+def get_mrrf(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "M"
+) -> pd.DataFrame:
+    """
+    Get International Reserves and Foreign Currency Liquidity data from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '1999-01-01'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'M'}, default 'M'
+        Data periodicity. Currently only monthly ('M') frequency is supported.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with datetime index and the following columns:
+        - TOTAL_RESERVES : Total international reserves (USD)
+        - CURRENCY_RESERVES : Currency reserves (USD)
+        - FOREIGN_CURRENCY : Foreign currency holdings (USD)
+        - SDR_ACCOUNT : Special Drawing Rights (SDR) account (USD)
+        - IMF_RESERVE : Reserve position in IMF (USD)
+        - MONETARY_GOLD : Monetary gold holdings (USD)
+
+    Notes
+    -----
+    International reserves are external assets that are readily available to and
+    controlled by monetary authorities for:
+    - Meeting balance of payments financing needs
+    - Intervention in exchange markets to affect currency exchange rate
+    - Other related purposes
+
+    All values are reported in US dollars.
+
+    Examples
+    --------
+    >>> get_mrrf('2020-01-01', '2023-12-31')
+    >>> get_mrrf(period='M')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="1999-01-01")
+    data2 = guess_date(last_date, default_value=str(today))
+    mrrf_xml = cbr_client.service.mrrf(data1, data2)
+
+    try:
+        df = pd.read_xml(mrrf_xml, xpath=".//mr")
+    except ValueError:
+        return pd.Series()
+
+    level_1_column_mapping = {
+        "p1": "TOTAL_RESERVES",
+        "p2": "CURRENCY_RESERVES",
+        "p3": "FOREIGN_CURRENCY",
+        "p4": "SDR_ACCOUNT",
+        "p5": "IMF_RESERVE",
+        "p6": "MONETARY_GOLD",
+    }
+
+    df = normalize_data(
+        data=df, period=period, symbol="mr", level_1=level_1_column_mapping
+    )
+
+    return df

cbrapi-0.1.0/cbrapi/ruonia.py

@@ -0,0 +1,257 @@
+from datetime import datetime, date
+from typing import Optional
+
+import pandas as pd
+
+from cbrapi.cbr_settings import make_cbr_client
+from cbrapi.helpers import normalize_data, guess_date
+
+
+today = date.today()
+
+
+def get_ruonia_ts(
+    symbol: str,
+    first_date: Optional[str] = None,
+    last_date: Optional[str] = None,
+    period: str = "D",
+) -> pd.Series:
+    """
+    Get RUONIA (Ruble Overnight Index Average) time series data from CBR.
+
+    Parameters
+    ----------
+    symbol : str
+        Financial instrument symbol. Supported symbols:
+        - 'RUONIA.INDX' : RUONIA index
+        - 'RUONIA_AVG_1M.RATE' : 1-month average rate
+        - 'RUONIA_AVG_3M.RATE' : 3-month average rate
+        - 'RUONIA_AVG_6M.RATE' : 6-month average rate
+        - Other symbols : return overnight RUONIA rates
+
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, returns
+        data from the earliest available date.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, returns
+        data up to the most recent available date.
+
+    period : {'D'}, default 'D'
+        Data periodicity. Currently only daily ('D') frequency is supported.
+
+    Returns
+    -------
+    pd.Series
+        Time series data for the requested symbol with datetime index.
+        Returns empty Series if no data is available for the given parameters.
+
+    Notes
+    -----
+    Data is sourced from the Central Bank of Russia (CBR) official statistics.
+    The function handles API requests and data parsing from CBR web services.
+
+    Examples
+    --------
+    >>> get_ruonia_ts('RUONIA.INDX', '2023-01-01', '2023-12-31')
+    >>> get_ruonia_ts('RUONIA_AVG_3M.RATE')
+    """
+    cbr_client = make_cbr_client()
+    if symbol in [
+        "RUONIA.INDX",
+        "RUONIA_AVG_1M.RATE",
+        "RUONIA_AVG_3M.RATE",
+        "RUONIA_AVG_6M.RATE",
+    ]:
+        ticker = (
+            symbol.split(".")[0] if symbol.split(".")[1] == "RATE" else "RUONIA_INDEX"
+        )
+        df = get_ruonia_index(first_date, last_date).loc[:, ticker]
+        if symbol != "RUONIA.INDX":
+            df /= 100
+        return normalize_data(df, period, symbol)
+    else:
+        return get_ruonia_overnight(first_date, last_date, period)
+
+
+def get_ruonia_index(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "D"
+) -> pd.DataFrame:
+    """
+    Get RUONIA index and averages time series from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '2010-01-01'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'D'}, default 'D'
+        Data periodicity. Currently only daily ('D') frequency is supported.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with datetime index and the following columns:
+        - RUONIA_INDEX : RUONIA index value
+        - RUONIA_AVG_1M : 1-month average rate (as decimal)
+        - RUONIA_AVG_3M : 3-month average rate (as decimal)
+        - RUONIA_AVG_6M : 6-month average rate (as decimal)
+
+    Notes
+    -----
+    RUONIA (Ruble Overnight Index Average) is the weighted average interest rate
+    on interbank loans and deposits. It serves as an indicator of the cost of
+    unsecured overnight borrowing.
+
+    Examples
+    --------
+    >>> get_ruonia_index('2023-01-01', '2023-12-31')
+    >>> get_ruonia_index(period='D')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="2010-01-01")
+    data2 = guess_date(last_date, default_value=str(today))
+    ruonia_index_xml = cbr_client.service.RuoniaSV(data1, data2)
+
+    try:
+        df = pd.read_xml(ruonia_index_xml, xpath=".//ra")
+    except ValueError:
+        return pd.Series()
+
+    level_1_column_mapping = {
+        "RUONIA_Index": "RUONIA_INDEX",
+        "R1W": "RUONIA_AVG_1M",
+        "R2W": "RUONIA_AVG_3M",
+        "R1M": "RUONIA_AVG_6M",
+    }
+
+    df = normalize_data(
+        data=df, period=period, symbol="ra", level_1=level_1_column_mapping
+    )
+    return df
+
+
+def get_ruonia_overnight(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "D"
+) -> pd.Series:
+    """
+    Get RUONIA overnight value time series from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '2010-01-01'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'D'}, default 'D'
+        Data periodicity. Currently only daily ('D') frequency is supported.
+
+    Returns
+    -------
+    pd.Series
+        Time series of RUONIA overnight rates with datetime index.
+        Rates are returned as decimals (e.g., 0.05 for 5%).
+
+    Notes
+    -----
+    RUONIA (Ruble Overnight Index Average) is the weighted average interest rate
+    on interbank loans and deposits. It serves as an indicator of the cost of
+    unsecured overnight borrowing.
+
+    Examples
+    --------
+    >>> get_ruonia_overnight('2023-01-01', '2023-12-31')
+    >>> get_ruonia_overnight(period='D')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="2010-01-01")
+    data2 = guess_date(last_date, default_value=str(date.today()))
+    ruonia_overnight_xml = cbr_client.service.Ruonia(data1, data2)
+
+    try:
+        df = pd.read_xml(ruonia_overnight_xml, xpath="//ro")
+    except ValueError:
+        return pd.Series()
+
+    level_1_column_mapping = {
+        "ruo": "RUONIA_OVERNIGHT",
+    }
+
+    df = normalize_data(
+        data=df, period=period, symbol="ro", level_1=level_1_column_mapping
+    )
+    df /= 100
+    return df
+
+
+def get_roisfix(
+    first_date: Optional[str] = None, last_date: Optional[str] = None, period: str = "D"
+) -> pd.DataFrame:
+    """
+    Get ROISfix (Ruble Overnight Index Swap Fixing) time series from CBR.
+
+    Parameters
+    ----------
+    first_date : str, optional
+        Start date in format 'YYYY-MM-DD'. If not specified, defaults to
+        '2011-04-15'.
+
+    last_date : str, optional
+        End date in format 'YYYY-MM-DD'. If not specified, defaults to
+        current date.
+
+    period : {'D'}, default 'D'
+        Data periodicity. Currently only daily ('D') frequency is supported.
+
+    Returns
+    -------
+    pd.DataFrame
+        DataFrame with datetime index and the following columns:
+        - RATE_1_WEEK : 1-week ROISfix rate (as decimal)
+        - RATE_2_WEEK : 2-week ROISfix rate (as decimal)
+        - RATE_1_MONTH : 1-month ROISfix rate (as decimal)
+        - RATE_2_MONTH : 2-month ROISfix rate (as decimal)
+        - RATE_3_MONTH : 3-month ROISfix rate (as decimal)
+        - RATE_6_MONTH : 6-month ROISfix rate (as decimal)
+
+    Notes
+    -----
+    ROISfix represents the fixed rate in ruble overnight index swaps.
+
+    Examples
+    --------
+    >>> get_roisfix('2023-01-01', '2023-12-31')
+    >>> get_roisfix(period='D')
+    """
+    cbr_client = make_cbr_client()
+    data1 = guess_date(first_date, default_value="2011-04-15")
+    data2 = guess_date(last_date, default_value=str(today))
+    roisfix_xml = cbr_client.service.ROISfix(data1, data2)
+
+    try:
+        df = pd.read_xml(roisfix_xml, xpath=".//rf")
+    except ValueError:
+        return pd.Series()
+
+    level_1_column_mapping = {
+        "R1W": "RATE_1_WEEK",
+        "R2W": "RATE_2_WEEK",
+        "R1M": "RATE_1_MONTH",
+        "R2M": "RATE_2_MONTH",
+        "R3M": "RATE_3_MONTH",
+        "R6M": "RATE_6_MONTH",
+    }
+
+    df = normalize_data(
+        data=df, period=period, symbol="rf", level_1=level_1_column_mapping
+    )
+    return df

cbrapi-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[tool.poetry]
+name = "cbrapi"
+version = "0.1.0"
+description = "Python interface for Central Bank of Russia (CBR) API"
+authors = [
+    "AAARRRT <artiomsalazov@gmail.com>",
+    "MBK Development LLC <info@rostsber.ru>"
+]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.10,<4.0.0"
+pandas = "^2.3.2"
+requests = "*"
+suds-py3 = "*"
+lxml = "*"
+
+[tool.poetry.group.dev.dependencies]
+black = "^25.1.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+