ecos-enhanced

Async Python client for Bank of Korea ECOS API

An asynchronous Python client for the Bank of Korea Economic Statistics System (ECOS) API. Easily query key economic indicators such as base interest rate, exchange rates, treasury bond yields, consumer price index, GDP, and more.

Features

• Async-first — Asynchronous HTTP client built on httpx
• Built-in registry — 12 major stat codes included (interest rates, exchange rates, prices, GDP, etc.)
• Convenience methods — One-liner queries via get_base_rate(), get_exchange_rate(), etc.
• Zero pandas dependency — Pure Python dataclasses
• Fully typed — py.typed marker with type hints on all public APIs

Installation

pip install ecos-enhanced

Quick Start

import asyncio
from ecos_enhanced import EcosClient

async def main():
    async with EcosClient(api_key="YOUR_ECOS_API_KEY") as client:
        # USD/KRW exchange rate
        rates = await client.get_exchange_rate("usd", "20240101", "20241231")
        for r in rates:
            print(f"{r.time}: {r.value} KRW")

        # Bank of Korea base interest rate
        base = await client.get_base_rate("202401", "202412")
        print(f"Current base rate: {base[-1].value}%")

        # Consumer Price Index
        cpi = await client.get_cpi("202401", "202412")
        print(f"Latest CPI: {cpi[-1].value}")

asyncio.run(main())

Error Handling

from ecos_enhanced import EcosClient, EcosApiError

async with EcosClient() as client:
    try:
        data = await client.get_by_key("usd_krw", "20240101", "20241231")
    except EcosApiError as e:
        print(f"ECOS API error: {e} (code={e.code})")

API Reference

EcosClient

client = EcosClient(api_key="...")  # or set the ECOS_API_KEY environment variable

EcosDataPoint

Return type (list) for all query methods:

Built-in Registry (STAT_CODES)

For statistics not in the registry, use get_statistic() to query directly.

Date Format

Environment Variables

ECOS API Key

1. Visit the ECOS API portal
2. Sign up and apply for an authentication key
3. Set the issued key as the ECOS_API_KEY environment variable or pass it to EcosClient(api_key="...")

Important Notes

Async Only

This library is designed for async/await usage only. To use it from synchronous code:

import asyncio
result = asyncio.run(main())

Statistics Query Limitations

• The ECOS API queries data using a combination of statistics table codes and item codes.
• For statistics not included in the built-in registry (STAT_CODES), look up the codes in the ECOS API documentation and use get_statistic() to query directly.

Disclaimer

This library is a technical tool for querying the Bank of Korea ECOS API and does not provide investment advice or financial services. Users are responsible for complying with the ECOS API Terms of Service and all applicable laws and regulations when using the data.

License

MIT License. See LICENSE.