ifdata-bcb

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

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:

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

# Excecoes e warnings (todos importaveis do top-level)
bcb.BacenAnalysisError  # Classe base de todos os erros
bcb.BacenWarning  # Classe base de todos os warnings

Metodos dos Explorers

Todos os explorers possuem:

Metodos especificos:

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.