Metadata-Version: 2.4
Name: bcbpy
Version: 1.2.0
Summary: Python client for the Banco Central do Brasil SGS (Sistema Gerenciador de Series Temporais) API with 115 curated series codes for Brazilian economic and financial time series.
Author-email: Rodrigo Teodoro <rodrigoteodoro.90@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/TeodoroRodrigo/bcbpy
Project-URL: Repository, https://github.com/TeodoroRodrigo/bcbpy
Project-URL: Issues, https://github.com/TeodoroRodrigo/bcbpy/issues
Project-URL: Changelog, https://github.com/TeodoroRodrigo/bcbpy/blob/main/CHANGELOG.md
Keywords: bcb,banco-central,brasil,brazil,sgs,economics,finance,time-series,ipca,selic,cdi,ptax
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
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
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Natural Language :: Portuguese (Brazilian)
Classifier: Natural Language :: English
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Dynamic: license-file

# bcbpy

Python client for the **BCB SGS** (Sistema Gerenciador de Series Temporais) API from the [Banco Central do Brasil](https://dadosabertos.bcb.gov.br/).

Fetch Brazilian economic and financial time series as pandas DataFrames with a simple, Pythonic interface. Includes **115 curated series codes** covering exchange rates, interest rates, inflation, GDP, employment, and more.

## Installation

```bash
pip install bcbpy
```

Or from source:

```bash
git clone https://github.com/TeodoroRodrigo/bcbpy.git
cd bcbpy
pip install -r requirements.txt
```

### Requirements

- Python 3.10+
- pandas
- requests

## Quick Start

```python
from bcbpy import fetch_series, fetch_last, fetch_multiple, INTEREST_RATES, EXCHANGE_RATES

# Last 10 CDI daily rates
cdi = fetch_last(INTEREST_RATES["CDI_DAILY"], n=10)
print(cdi)

# USD/BRL exchange rate for 2024
usd = fetch_series(EXCHANGE_RATES["USD_SALE_DAILY"], start_date="2024-01-01", end_date="2024-12-31")
print(usd)

# Multiple series merged into one DataFrame
df = fetch_multiple(
    {"CDI": INTEREST_RATES["CDI_DAILY"], "SELIC": INTEREST_RATES["SELIC_DAILY"]},
    start_date="2024-01-01",
    end_date="2024-12-31",
)
print(df.tail())
```

## API Reference

### Functions

#### `fetch_series(code, start_date=None, end_date=None)`

Fetch a time series by its SGS numeric code. Returns a pandas DataFrame indexed by date.

```python
from bcbpy import fetch_series

# Accepts YYYY-MM-DD or DD/MM/YYYY date formats
ipca = fetch_series(433, start_date="2023-01-01", end_date="2024-12-31")
```

#### `fetch_last(code, n=10)`

Fetch the last N observations of a series.

```python
from bcbpy import fetch_last

selic = fetch_last(11, n=5)
```

#### `fetch_multiple(codes_dict, start_date=None, end_date=None)`

Fetch multiple series and merge them into a single DataFrame, one column per series.

```python
from bcbpy import fetch_multiple

df = fetch_multiple({"CDI": 12, "SELIC": 11, "TR": 226}, start_date="2024-01-01")
```

#### `list_codes(category=None)`

Print all available series codes. Pass a category name to filter.

```python
from bcbpy import list_codes

list_codes()                        # all 115 codes across 14 categories
list_codes("INTEREST_RATES")        # only interest rate codes
```

#### `search_codes(keyword)`

Search codes by keyword (case-insensitive). Returns a dict of matches.

```python
from bcbpy import search_codes

results = search_codes("IPCA")      # finds 15 IPCA-related codes
results = search_codes("USD")       # finds USD exchange rate codes
```

### Exceptions

| Exception | When |
|-----------|------|
| `SGSError` | Base exception for all API errors |
| `SGSRateLimitError` | API returns HTTP 429 (too many requests) |
| `SGSEmptyResponseError` | No data returned for the given query |

### Error Handling

```python
from bcbpy import fetch_series, SGSRateLimitError, SGSEmptyResponseError

try:
    df = fetch_series(433, start_date="2024-01-01")
except SGSRateLimitError:
    print("Rate limited — wait and retry")
except SGSEmptyResponseError:
    print("No data for this date range")
```

## Available Series Codes

115 curated codes organized in 14 categories:

| Category | Series | Examples |
|----------|--------|----------|
| `EXCHANGE_RATES` | 6 | USD/BRL daily sale/purchase, monthly averages |
| `INTEREST_RATES` | 10 | Selic, CDI, TR, TBF, TJLP |
| `INFLATION` | 17 | IPCA, INPC, IGP-M, IGP-DI, IPC-Fipe |
| `IPCA_BREAKDOWN` | 11 | Tradeable, non-tradeable, durables, services, cores |
| `IPCA_CATEGORIES` | 9 | Food, housing, transport, health, education |
| `GDP` | 13 | GDP current/constant/USD, per capita, quarterly components |
| `EMPLOYMENT` | 7 | Unemployment rate, labor force, income |
| `INDUSTRIAL_PRODUCTION` | 7 | Manufacturing, mining, capital/intermediate/consumer goods |
| `FINANCIAL_MARKETS` | 7 | Gold, Bovespa, IMA-B |
| `SAVINGS` | 2 | Savings rate and return |
| `CONFIDENCE` | 4 | Consumer (ICC) and business (ICEI) confidence |
| `ECONOMIC_ACTIVITY` | 1 | IBC-Br (GDP proxy, seasonally adjusted) |
| `BASIC_BASKET` | 16 | Cost of living by capital city |
| `EXCHANGE_RATE_INDEX` | 5 | Real effective exchange rate (USD, EUR, JPY, ARS) |

Use any code directly by number or via the category dictionaries:

```python
from bcbpy import INFLATION, GDP

# These are equivalent:
fetch_series(433)
fetch_series(INFLATION["IPCA"])
```

## API Limits

- **Date range:** max 10 years per query (BCB restriction since March 2025)
- **Rate limiting:** HTTP 429 on excessive requests (no official limit documented)
- **Date formats:** the client accepts both `YYYY-MM-DD` and `DD/MM/YYYY`

## Project Structure

```
bcbpy/
├── bcbpy/
│   ├── __init__.py      # Public API exports
│   ├── client.py        # API client functions and exceptions
│   ├── codes.py         # 115 curated series codes in 14 categories
│   └── constants.py     # Base URLs and API configuration
├── main.py              # CLI demo script
├── pyproject.toml       # PyPI packaging metadata
├── BCB_API_REFERENCE.md # Full SGS + Olinda API reference guide
└── README.md
```

## Data Source

All data is fetched from the [BCB Open Data Portal](https://dadosabertos.bcb.gov.br/) under the [Open Database License (ODbL)](https://opendatacommons.org/licenses/odbl/).

## License

MIT (see [LICENSE](LICENSE)). The BCB data accessed through this client remains under ODbL; users must comply with ODbL when redistributing data.
