wilsonfreitas/python-bcb

python-bcb

python-bcb é uma interface em Python estruturada para obter informações da API de dados abertos do Banco Central do Brasil.

O projeto de Dados Abertos do Banco Central do Brasil disponibiliza diversas APIs provendo acesso direto a dados de:

• Moedas
• Taxas de Juros
• Índices de preços
• Informações de Instituições Financeiras
• Expectativas do Mercado (Expectativas do Boletim FOCUS)
• E muito mais...

Instalação

python-bcb está disponível no Python Package Index e pode ser instalado via pip.

pip install python-bcb

APIs

SGS - Sistema Gerenciador de Séries Temporais

Utiliza o webservice do SGS (Sistema Gerenciador de Séries Temporais) para obter dados históricos de indicadores econômicos. Oferece a maior base de dados históricos com diversas séries temporais.

Conversor de Moedas

Implementado no módulo currency, realiza webscraping no site do Conversor de Moedas do Banco Central. Fornece séries temporais de frequência diária de taxas de câmbio (cotações de compra e venda).

OData - APIs Estruturadas

O Banco Central disponibiliza diversas informações em APIs que seguem o padrão OData. Inclui:

• PTAX: Boletins diários de taxas de câmbio com dados institucionalmente detalhados
• Expectativas: Expectativas de mercado coletadas do Boletim FOCUS
• TaxaJuros: Diversas taxas de juros (Selic, CDI, Cheque especial, etc.)
• MercadoImobiliario: Dados de financiamento imobiliário
• IFDATA: Informações de instituições financeiras
• SPI: Sistema de Pagamentos Instantâneos

Qual Módulo Devo Usar?

Use esta tabela para escolher o módulo certo para seu caso de uso:

Início Rápido

Séries Temporais com SGS

from bcb import sgs

# Buscar taxa Selic (código 1)
df = sgs.get(1, start="2023-01-01", end="2024-12-31")

Taxas de Câmbio com Currency

from bcb import currency

# Buscar preços de compra/venda do USD
usd = currency.get("USD", start="2023-01-01", end="2024-12-31")

Expectativas de Mercado com OData

from bcb import Expectativas

api = Expectativas()
endpoint = api.get_endpoint("ExpectativasMercadoAnuais")

# Obter previsões do IPCA
df = endpoint.query().filter(endpoint.Indicador == "IPCA").limit(100).collect()

Perguntas Frequentes

P: Qual é a diferença entre dados de moedas do SGS e PTAX?

R: SGS contém principalmente indicadores econômicos. Para taxas de câmbio, use bcb.currency (dados PTAX) para cotações diárias ou o serviço bcb.odata PTAX para dados institucionais detalhados. O módulo currency é mais simples para casos comuns.

P: Quão longe no tempo os dados históricos vão?

R: Varia por série:

• SGS: Maioria das séries remontam aos anos 1980/1990 (verifique documentação específica do código)
• Currency: Cotações diárias disponíveis desde aproximadamente 1980
• Serviços OData: Varia; consulte documentação BCB para endpoints específicos

P: Posso buscar dados de forma assíncrona?

R: Sim. SGS e currency oferecem async_get(), e os endpoints OData oferecem async_get() e async_collect(). Feche o cliente assíncrono ao final de aplicações de longa duração:

import asyncio
from bcb import http, sgs

async def main():
    try:
        results = await asyncio.gather(
            sgs.async_get(1),  # SELIC
            sgs.async_get(433),  # IPCA
        )
        return results
    finally:
        await http.aclose_async_client()

asyncio.run(main())

P: Como aumento o timeout de uma consulta lenta?

R: Passe timeout na própria chamada. O valor é local daquela chamada e não altera o cliente HTTP compartilhado globalmente:

from bcb import sgs, currency, Expectativas

# SGS
selic = sgs.get(11, start="1990-01-01", timeout=120)

# Currency
usd = currency.get("USD", start="1980-01-01", end="2026-01-01", timeout=120)

# OData
em = Expectativas(timeout=120)
ep = em.get_endpoint("ExpectativasMercadoAnuais")
df = ep.query().limit(1000).collect(timeout=120)

O padrão continua sendo 30 segundos. No SGS, o timeout vale por tentativa HTTP; quando houver retry, cada tentativa usa o mesmo valor.

P: Como trato erros e dados faltantes?

R: A biblioteca lança exceções específicas:

• CurrencyNotFoundError: Símbolo de moeda não encontrado
• SGSError: Erro do serviço SGS
• BCBRateLimitError: Limite de requisições excedido (HTTP 429)
• BCBAPIError: Outros erros de API

from bcb import sgs
from bcb.exceptions import SGSError, BCBRateLimitError

try:
    df = sgs.get(99999)  # Código inválido
except SGSError as e:
    print(f"Erro de dados: {e}")
except BCBRateLimitError:
    print("Limite de requisições excedido - tente novamente mais tarde")

P: Como habilito logging para depurar requisições?

R: A biblioteca usa o módulo logging padrão do Python:

import logging

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("bcb")
logger.setLevel(logging.DEBUG)

# Agora todas as requisições/respostas HTTP serão registradas

P: Existe cache para evitar requisições redundantes?

R: Sim:

• bcb.currency: Cache em memória automático de listas de moedas
• bcb.odata: Metadados OData em cache por URL de serviço
• Chame currency.clear_cache() para resetar se dados mudarem

P: Posso usar isso em uma aplicação de longa duração?

R: Sim, mas tenha cuidado com:

• Limites de requisições: APIs BCB podem ter limites; implemente backoff se necessário
• Cache: Cache de moedas persiste em memória; limpe se atualizações de dados importarem
• Pool de conexões: Usa httpx com connection pooling por padrão
• API Assíncrona: use métodos async para comportamento verdadeiramente não-bloqueante e chame await bcb.http.aclose_async_client() no encerramento de aplicações assíncronas longas

P: Como contribuo ou reporto problemas?

R: Visite o repositório GitHub para:

• Reportar bugs
• Solicitar features
• Enviar pull requests
• Ver documentação

P: Como gero a documentação localmente?

R: As dependências de documentação ficam no grupo docs do uv:

uv run --group docs sphinx-build -b html docs docs/_build/html

A saída HTML é gerada em docs/_build/html. Edite os arquivos fonte em docs/; não edite os arquivos gerados em docs/_build.

P: Onde encontro documentação mais detalhada?

R:

• Documentação de API
• Diretório de Exemplos
• Docstrings inline: help(bcb.sgs.get), help(bcb.currency.get), etc.
• Portal de Dados Abertos BCB