Como eu resolvi o limite de 10 anos da API do Banco Central do Brasil com Python

Source: Dev.to

Source: Dev.to – “Como eu resolvi o limite de 10 anos da API do Banco Central do Brasil com Python (POH)”

O problema em detalhes

A API SGS do Banco Central é pública e gratuita. Você faz uma requisição HTTP com o código da série, data inicial e data final, e recebe um JSON com os valores.

Até 2025, era possível consultar qualquer período:

GET https://api.bcb.gov.br/dados/serie/bcdata.sgs.1/dados?formato=json&dataInicial=01/01/1984&dataFinal=31/12/2025

A partir de 2025, se o intervalo for maior que 10 anos, a API devolve erro 400 ou uma resposta vazia. Para obter a cotação completa do Dólar (código 1), que existe desde 1984, seria necessário fazer ao menos 5 requisições separadas, concatenar os resultados e remover duplicatas.

É exatamente isso que o BacenData automatiza.

A solução: paginação automática

pip install bacendata

from bacendata import sgs

# Série completa do Dólar — 40+ anos em uma chamada
dolar = sgs.get("dolar", start="1984-01-01")
print(f"{len(dolar)} registros de {dolar.index[0]} a {dolar.index[-1]}")

Como funciona por dentro

O resultado é um pandas.DataFrame limpo, pronto para análise.

Funcionalidades principais

1️⃣ Aliases para séries populares

Em vez de decorar códigos numéricos, use nomes:

# Estes são equivalentes
sgs.get(1, start="2020-01-01")
sgs.get("dolar", start="2020-01-01")

O BacenData vem com 14 séries pré‑configuradas:

2️⃣ Múltiplas séries de uma vez

df = sgs.get(
    {"Selic": 11, "IPCA": 433, "Dólar": 1},
    start="2015-01-01"
)
print(df.head())

Resultado

                Selic   IPCA  Dólar
data
2015-01-02  0.046189    NaN  2.694
2015-01-05  0.046189    NaN  2.702
...

3️⃣ Últimos N valores

# Últimos 12 valores do IPCA
ipca = sgs.get("ipca", last=12)

4️⃣ Cache inteligente

O BacenData mantém um cache SQLite local com TTL automático por tipo de série:

# Desativar cache se necessário
from bacendata.wrapper.cache import desativar
desativar()

5️⃣ Metadados das séries

meta = sgs.metadata(1)
print(meta)
# {'codigo': 1,
#  'nome': 'Taxa de câmbio - Livre - Dólar americano (venda) - diário',
#  'periodicidade': 'D',
#  'unidade': 'u.m.c./US$', ...}

Arquitetura interna

bacendata/
├── wrapper/
│   ├── bacen_sgs.py    # Core: get(), aget(), metadata()
│   ├── catalogo.py     # 14 séries pré‑configuradas
│   ├── cache.py        # Cache SQLite com TTL
│   └── exceptions.py   # Exceções customizadas
├── api/
│   ├── app.py          # FastAPI app factory
│   └── routes/         # Endpoints REST
└── schemas/
    └── series.py       # Pydantic models

Paginação em detalhe

O coração do BacenData é a função _buscar_com_paginacao:

async def _buscar_com_paginacao(codigo, inicio, fim, client):
    intervalos = _gerar_intervalos(inicio, fim, max_anos=10)
    semaforo = asyncio.Semaphore(5)

    async def fetch_com_semaforo(ini, fi):
        async with semaforo:
            try:
                return await _buscar_serie_periodo(codigo, ini, fi, client)
            except (SerieNaoEncontrada, BacenAPIError):
                return []  # Intervalo sem dados, não aborta

    tasks = [fetch_com_semaforo(ini, fi) for ini, fi in intervalos]
    resultados = await asyncio.gather(*tasks)

    todos_dados = [item for sublista in resultados for item in sublista]
    if not todos_dados:
        raise SerieNaoEncontrada(codigo)
    return todos_dados

• Semaphore(5) garante que nunca haja mais de 5 conexões paralelas, evitando sobrecarga no servidor do BACEN.
• Cada intervalo é tratado de forma independente; falhas em um intervalo não abortam a consulta completa.

Com o BacenData, você obtém dados históricos completos do Banco Central de forma simples, rápida e segura, sem precisar se preocupar com a limitação de 10 anos da API oficial. 🚀

# BacenData – Biblioteca Python para Dados do Banco Central

## Instalação
```bash
pip install bacendata

Uso rápido

import asyncio
from bacendata import buscar_serie

async def main():
    dados = await buscar_serie(codigo='432', inicio='2000-01-01', fim='2023-12-31')
    print(dados)

asyncio.run(main())

Recursos

• Paginação automática (até 10 anos por requisição)
• Limite de concorrência controlado por asyncio.Semaphore
• Tratamento robusto de erros (intervalos vazios não interrompem a execução)

BacenData simplifica o acesso a séries temporais do Banco Central, permitindo que desenvolvedores foquem na análise e não na coleta de dados.

## Problema resolvido

O `fetch_com_semaforo` resolve outro problema sutil: quando o usuário pede **“todos os dados disponíveis”**, o BacenData gera intervalos desde 1960. Para séries que começaram em 1984, os intervalos de `1960‑1970` e `1970‑1980` retornam **404**. Sem o `try/except`, o `asyncio.gather` falharia inteiramente.

## Stack técnica

- **httpx** (async) – cliente HTTP escolhido por suporte nativo a *async*, ao contrário do `requests`.
- **asyncio** – paralelismo de I/O para paginação.
- **pandas** – retorno em `DataFrame` para integração fácil com o ecossistema Python de dados.
- **SQLite** – cache local leve, sem dependências extras.
- **FastAPI** – API REST com documentação automática (Swagger / ReDoc).
- **Streamlit** + **Plotly** – dashboard interativo para não‑programadores.

## API REST

O **BacenData** também expõe uma API REST para integração com qualquer linguagem ou sistema.

### Instalação e execução

```bash
# Instalar
pip install bacendata[api]

# Executar
uvicorn bacendata.api.app:create_app --factory --port 8000

Endpoints disponíveis

Exemplo de uso

curl "http://localhost:8000/api/v1/series/1?start=2025-01-01&end=2025-01-05"

Resposta

{
  "codigo": 1,
  "nome": "Taxa de câmbio - Livre - Dólar americano (venda) - diário",
  "dados": [
    { "data": "2025-01-02", "valor": 6.1797 },
    { "data": "2025-01-03", "valor": 6.1627 },
    { "data": "2025-01-04", "valor": 6.1503 },
    { "data": "2025-01-05", "valor": 6.1389 },
    { "data": "2025-01-06", "valor": 6.1275 }
  ],
  "total_registros": 5
}

Dashboard Interativo

Para quem não programa, o BacenData oferece um dashboard público em Streamlit:

https://bacendata.streamlit.app

Principais funcionalidades

• Gráficos interativos com zoom e hover
• Comparação lado a lado de até 3 séries
• Média móvel configurável
• Exportação em CSV ou Excel
• Acesso a todos os 14 indicadores disponíveis

Como contribuir

O projeto é open source (MIT). Algumas ideias para contribuição:

• Adicionar novas séries ao catálogo
• Integrar com a API de expectativas Focus (séries futuras)
• Criar wrappers para R ou JavaScript
• Melhorar a documentação

Links úteis

• GitHub: <insira o link aqui>
• PyPI: <insira o link aqui>
• Dashboard: <insira o link aqui>
• Site: <insira o link aqui>

Se você trabalha com dados econômicos no Brasil — como economista, analista, desenvolvedor ou pesquisador — o BacenData pode te poupar horas de trabalho manual. Dá uma olhada e me conta o que achou.