ifdata-bcb 0.4.0

Analise de dados financeiros do Banco Central do Brasil (BCB)

ifdata-bcb

Coleta e analise de dados contabeis e financeiros de instituicoes financeiras brasileiras. Dados publicos do Banco Central do Brasil.

Fonte	Modulo	Dados	Periodicidade
COSIF	bcb.cosif	Plano contabil (individual e prudencial)	Mensal
IFDATA	bcb.ifdata	Informacoes financeiras	Trimestral
Cadastro	bcb.cadastro	Metadados de instituicoes (segmento, conglomerado)	Trimestral

Instalacao

uv add ifdata-bcb

Requer Python 3.12+.

Uso Rapido

import ifdata_bcb as bcb

# 1. Coletar dados (primeira vez ou atualizar)
bcb.cadastro.collect('2024-01', '2024-12')
bcb.cosif.collect('2024-01', '2024-12')
bcb.ifdata.collect('2024-01', '2024-12')

# 2. Buscar instituicao por nome (fuzzy matching)
bcb.cadastro.search('Itau')
bcb.cadastro.search('Bradesco')
#    CNPJ_8                       INSTITUICAO  SITUACAO       FONTES  SCORE
# 0  60872504  ITAU UNIBANCO HOLDING S.A.           A  cosif,ifdata    100

# 3. Ler dados usando CNPJ de 8 digitos
# start e OBRIGATORIO (posicional); instituicao e keyword-only e opcional
# start sozinho = data unica; start + end = range

# COSIF (escopo=None busca em todos os escopos)
df = bcb.cosif.read(
    '2024-12',
    instituicao='60872504',
    conta='TOTAL GERAL DO ATIVO',
    escopo='prudencial'
)

# IFDATA
df = bcb.ifdata.read(
    '2024-01',
    '2024-12',
    instituicao='60872504',
    conta='Lucro Liquido'
)

# Bulk read: todas as instituicoes (sem instituicao)
df = bcb.cosif.read('2024-12', escopo='prudencial')

# Enriquecer com dados cadastrais inline
df = bcb.ifdata.read(
    '2024-01',
    '2024-12',
    instituicao='60872504',
    escopo='prudencial',
    cadastro=['TCB', 'SEGMENTO']
)

# Cadastro
df = bcb.cadastro.read('2024-12', segmento='Banco Multiplo')

# 4. Listar valores distintos e contas
bcb.ifdata.list(["RELATORIO"])
bcb.cosif.list(["DATA", "ESCOPO"])
bcb.cadastro.list(["SEGMENTO"], uf='SP')
bcb.cosif.list_contas(escopo='prudencial')

# 5. SQL direto com DuckDB (para analises avancadas)
from ifdata_bcb.infra import QueryEngine

qe = QueryEngine()
df = qe.sql("""
    SELECT CNPJ_8, NOME_INSTITUICAO, SALDO
    FROM '{cache}/cosif/prudencial/*.parquet'
    WHERE DATA_BASE = 202412 AND NOME_CONTA = 'TOTAL GERAL DO ATIVO'
    ORDER BY SALDO DESC
    LIMIT 10
""")

Documentacao

Guias de Uso

• getting-started.md - Instalacao e primeiro uso

Fontes de Dados

• cosif.md - Plano contabil (individual/prudencial)
• ifdata.md - Informacoes financeiras trimestrais
• cadastro.md - Metadados de instituicoes

Uso Avancado

• sql-queries.md - Queries SQL com DuckDB
• extending.md - Como criar novos providers

Arquitetura Interna

• architecture.md - Visao geral da arquitetura
• core.md - EntityLookup, Constants, Eras, BaseExplorer
• domain.md - Exceptions, Types, Validation
• infra.md - Settings, QueryEngine, DataManager
• providers.md - BaseCollector, Explorers

Estrutura de Dados

{cache}/
  cosif/
    individual/       # cosif_ind_YYYYMM.parquet
    prudencial/       # cosif_prud_YYYYMM.parquet
  ifdata/
    valores/          # ifdata_val_YYYYMM.parquet
    cadastro/         # ifdata_cad_YYYYMM.parquet

O diretorio de cache varia por sistema:

Sistema	Caminho
Windows	%LOCALAPPDATA%\py-bacen\Cache\
Linux	~/.cache/py-bacen/
macOS	~/Library/Caches/py-bacen/

Customizavel via variavel de ambiente BACEN_DATA_DIR.

API Publica

Modulo Principal

import ifdata_bcb as bcb

# Explorers (lazy loading)
bcb.cosif       # COSIFExplorer
bcb.ifdata      # IFDATAExplorer
bcb.cadastro    # CadastroExplorer

# Exceptions
bcb.BacenAnalysisError       # Classe base para todos os erros
bcb.DataUnavailableError     # Dados nao disponiveis

Metodos dos Explorers

Todos os explorers possuem:

Metodo	Descricao
collect(start, end, ...)	Coleta dados do BCB
read(start, end, *, instituicao, ...)	Le dados com filtros (start posicional, demais keyword-only)
list(columns, *, ...)	Lista valores distintos para colunas (SELECT DISTINCT)
list_periodos()	Periodos disponiveis
describe()	Metadados do provider (inclui columns aceitas por list())
has_data()	Verifica se tem dados

Metodos especificos:

Explorer	Metodos Adicionais
cosif	list_contas()
ifdata	list_contas(), mapeamento()
cadastro	search()

Limitacoes Conhecidas

• Dependencia de APIs do BCB: a coleta depende da disponibilidade dos endpoints publicos do Banco Central. Se a API estiver fora do ar ou mudar seu schema, a coleta pode falhar.
• Dados historicos: nem todos os periodos estao disponiveis para todas as fontes. Use list_periodos() para verificar disponibilidade.
• Primeira coleta lenta: a coleta inicial de dados pode demorar dependendo do range de datas solicitado, pois faz multiplas requisicoes HTTP ao BCB (paralelas com 4 workers).
• Cache sem invalidacao automatica: dados coletados ficam em cache local indefinidamente. Para atualizar, colete novamente o periodo desejado.
• Sem suporte offline: a coleta requer conexao com a internet. A leitura funciona offline se os dados ja estiverem em cache.

Contribuindo

Contribuicoes sao bem-vindas! Consulte o guia de contribuicao para detalhes sobre como participar.

Licenca

Distribuido sob a licenca MIT. Veja LICENSE para mais informacoes.