Title:	Access Data from Brazilian Central Bank: IFdata, Active Institutions, Balance Sheets and Normative Acts
Version:	0.3.1
Description:	Provides functions to query, retrieve, and tidy economic and financial data from Brazilian Central Bank web services for use in R analyses and workflows. Active institutions information, balance sheets and normative acts.
License:	GPL (≥ 3)
URL:	https://github.com/rtheodoro/bacenR
BugReports:	https://github.com/rtheodoro/bacenR/issues
Depends:	R (≥ 4.1.0)
Imports:	data.table, dplyr, fs, glue, httr, janitor, jsonlite, lifecycle, purrr, readr, readxl, rlang, stringr, tibble, tidyr, tools, utils, xml2
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
VignetteBuilder:	knitr
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.3
SystemRequirements:	qpdf
NeedsCompilation:	no
Packaged:	2026-03-03 18:24:57 UTC; gengar
Author:	Ricardo Theodoro [aut, cre]
Maintainer:	Ricardo Theodoro <rtheodoro@usp.br>
Repository:	CRAN
Date/Publication:	2026-03-08 10:00:08 UTC

bacenR: Access Data from Brazilian Central Bank: IFdata, Active Institutions, Balance Sheets and Normative Acts

Description

Provides functions to query, retrieve, and tidy economic and financial data from Brazilian Central Bank web services for use in R analyses and workflows. Active institutions information, balance sheets and normative acts.

Author(s)

Maintainer: Ricardo Theodoro rtheodoro@usp.br (ORCID)

See Also

Useful links:

• https://github.com/rtheodoro/bacenR

• Report bugs at https://github.com/rtheodoro/bacenR/issues

Download balance sheets from Brazilian Central Bank

Description

Downloads monthly "balancetes" (.CSV or .ZIP) released by the Brazilian Central Bank for one or more institution types and stores them in a local directory. ZIP files found in the destination directory are also extracted (errors during individual extractions are ignored).

Check the function tidy_balance_sheets() for tools to read and process

Usage

get_balance_sheets(
  institution,
  months = 12,
  first_year,
  final_year,
  out_dir,
  overwrite = FALSE
)

Arguments

Details

For each combination of year, month and institution type the function constructs a URL of the form: ⁠https://www.bcb.gov.br/content/estabilidadefinanceira/cosif/{tipo}/{YYYY}{MM}{institution}.CSV.ZIP⁠ and attempts to download it with httr::GET. Successful and failed attempts are recorded in the returned tibble. After attempting all downloads the function tries to unzip any .zip files found in out_dir; unzip errors for individual files are caught and ignored so the process continues.

Invalid institution tokens cause an immediate error listing the invalid entries.

Value

A tibble with one row per attempted download and the following columns:

• years: Year attempted (integer).

• months: Month attempted (integer).

• institution: Institution token used (character).

• url: The URL attempted (character).

• dest: Destination file path for the downloaded ZIP (character).

• success: Logical indicating if the download (or existing-file fallback) was considered successful.

• http_status: HTTP status code returned by the request (integer NA if not available).

• error: Character string with an error message when success is FALSE, or a short note when a local file existed and was not overwritten.

References

Source Banco Central do Brasil (Bacen): https://www.bcb.gov.br/estabilidadefinanceira/balancetesbalancospatrimoniais Note: The values are not changed or processed in any way, they are downloaded as-is from the source. Check the function treat_balance_sheets() for tools to read and process Site: https://www.bcb.gov.br/estabilidadefinanceira/balancetesbalancospatrimoniais

Examples

# Download balance sheets of credit unions for December of 2023
get_balance_sheets(
  institution = "COOPERATIVAS",
  months = 12,
  first_year = 2023,
  final_year = 2023,
  out_dir = tempdir(),
  overwrite = FALSE
)


# Download balance sheets of credit unions for December of 2023
get_balance_sheets(
  institution = c("BANCOS", "COOPERATIVAS"),
  months = c(6, 12),
  first_year = 2022,
  final_year = 2023,
  out_dir = tempdir(),
  overwrite = FALSE
)

Download institution registry data from IFdata of Brazilian Central Bank (Bacen) Cadastro

Description

Download institution registry data from the Brazilian Central Bank (Bacen) IFdata API for specified years and months. The function handles multiple combinations of parameters and returns a consolidated data frame with the results.

Usage

get_ifdata_registry(year, month, verbose = TRUE)

Arguments

Value

Data frame with institution registry data or NULL in case of error

Examples

# Single period
data <- get_ifdata_registry(
 year = 2024,
 month = 12
)
# Multiple years and months (all combinations), take some time to run
data <- get_ifdata_registry(
 year = c(2023, 2024),
 month = c(3, 6, 9, 12)
)

Download institution reports data from IFdata of Brazilian Central Bank (Bacen) Relatorios

Description

Download IFdata reports from the Brazilian Central Bank (Bacen) API for specified years, months, institution types, and report types. The function handles multiple combinations of parameters and returns a consolidated data frame with the results.

Also, check the page to see the available reports for each institution type and date: IFdata.

Usage

get_ifdata_reports(year, month, type_institution, report, verbose = TRUE)

Arguments

Value

Data frame with IFdata values or NULL in the case of errors.

Examples

# Unique institution type for a specific period
data <- get_ifdata_reports(
 year = 2024,
 month = 12,
 report = 1,
 type_institution = 2
)

# Multiple periods, take some time to run
data <- get_ifdata_reports(
  year = c(2023, 2024),
  month = c(6, 12),
  report = 1,
  type_institution = 2
)

Download and Process Brazilian Financial Institutions Data from Bacen

Description

This function downloads financial institutions data from the Brazilian Central Bank (Bacen) website for specified institution types and date ranges. The data is downloaded as ZIP files, extracted, and can be optionally cleaned up.

Usage

get_institutions(
  institution,
  start_date,
  end_date,
  out_dir,
  cleanup_zip = TRUE,
  verbose = TRUE
)

Arguments

Details

The function performs the following steps:

• Validates institution types against known valid options

• Generates a sequence of months between start_date and end_date

• Downloads ZIP files for each institution and month from BCB website

• Extracts the downloaded ZIP files to the output directory

• Optionally removes ZIP files after extraction

• Displays progress information if verbose = TRUE

Institution type mappings:

• CONGLOMERADOS: Conglomerados

• BANCOS: Bancos comerciais, múltiplos e caixa

• COOPERATIVAS: Cooperativas de crédito

• CONSORCIO: Consórcios administrativos

• SOCIEDADES: Bancos de investimentos, desenvolvimento e sociedades corretoras

Value

Invisible NULL. The function is called for its side effects (downloading and extracting files to the specified directory).

See Also

https://www.bcb.gov.br/estabilidadefinanceira/relacao_instituicoes_funcionamento

Examples

# Download cooperative credit unions data for 2023
get_institutions(
  institution = "COOPERATIVAS",
  start_date = "202311",
  end_date = "202312",
  out_dir = tempdir()
)

# Download multiple institution types
get_institutions(
  institution = c("BANCOS", "COOPERATIVAS"),
  start_date = "202201",
  end_date = "202212",
  out_dir = tempdir()
)

# Skip downloading, just use existing files
get_institutions(
  institution = "BANCOS",
  start_date = "202201",
  end_date = "202212",
  out_dir = tempdir(),
  verbose = FALSE
)

Download normative acts from the Brazilian Central Bank (Bacen) by terms and date range

Description

Queries the Bacen normative search API, collects all results within the provided date range and returns a data.frame with the records. Data are downloaded from https://www.bcb.gov.br/estabilidadefinanceira/buscanormas.

Usage

get_normative_data(terms, ini_date, end_date)

Arguments

Details

1. Builds the query URL using the terms and the date range.

2. Retrieves the total number of results to determine the page size.

3. Iterates over result pages (incrementing by 500) until a page returns fewer than 13 rows (stop condition).

4. Performs simple cleaning on returned fields:

   • removes "string;#" prefixes,

   • removes HTML tags in summaries and subjects,

   • removes the decimal part of normative numbers.

Value

data.frame containing the records returned by the API and the post-processed columns.

Examples

ini_date <- "2025-01-01"
end_date <- "2025-01-05"
terms <- c("Cooperativas", "Cooperativa")
normas <- get_normative_data(terms, ini_date, end_date)

Download normative texts from the Brazilian Central Bank (Bacen) from a reference data.frame

Description

For each row of the input data.frame, constructs the appropriate URL for the Bacen normatives API, performs the request, extracts the returned content and applies basic cleaning to the text fields (Assunto and Texto). Returns a data.frame with all aggregated contents.

Usage

get_normative_txt(normative_data)

Arguments

Details

The function performs the following steps:

1. Iterates over each row of normative_data (prints the iteration index for monitoring).

2. Encodes the normative type for URL usage (using URLencode(..., reserved = TRUE)).

3. Chooses the API route depending on the type:

   • for "Comunicado", "Ato de Diretor" and "Ato do Presidente" it uses the other-norms endpoint (exibeoutrasnormas);

   • for the rest, it uses the standard normative endpoint (exibenormativo).

4. Makes the HTTP request (via httr::GET) and converts the returned JSON into a data.frame.

5. Extracts and cleans textual fields:

   • converts HTML to plain text for the fields Assunto and Texto (using xml2::read_html + xml2::xml_text),

   • removes line breaks and extra spaces (stringr::str_replace_all, stringr::str_squish).

6. Aggregates each result into a final data.frame returned by the function.

Value

data.frame with the records returned by the API for each reference in normative_data, including the extracted and post-processed fields (e.g., Assunto, Texto).

Note

• The function assumes the BCB API returns a conteudo field with the expected fields.

• Request errors or changes in the API structure may cause failures; consider handling exceptions around the call if needed.

• Packages used internally: httr, jsonlite, xml2, stringr, dplyr, glue, purrr.

Examples

# First, download normative data
normative_data <- get_normative_data(
   "Cooperativa",
    "2023-08-01",
    "2023-08-10")
# Then, download the full texts for the retrieved normatives
normative_txt <- get_normative_txt(normative_data)

Import balancete CSV files with flexible header detection

Description

Imports CSV files from BCB by detecting the header line that contains the tokens "DOCUMENTO", "CONTA", and "SALDO" (case-insensitive). Automatically renames columns and removes unnecessary fields.

This function is intended for internal use by tidy_balance_sheets()

Usage

import_balance_sheets(file_paths)

Arguments

Details

For each file:

1. Reads line-by-line searching for a header containing DOCUMENTO, CONTA, and SALDO

2. Auto-detects delimiter (⁠;⁠, ⁠,⁠, or whitespace)

3. Imports using data.table::fread for speed and robustness

4. Renames: DATA_BASE/DATA BASE/#DATA_BASE -> DATA, NOME INSTITUICAO -> nome_instituicao

5. Removes columns: ATRIBUTO, NOME CONTA, AGENCIA, COD_CONGL, NOME_CONGL, TAXONOMIA, NOME_CONTA

6. Returns combined data.frame from all files

Value

A data.frame combining all imported files, or NULL if no valid files.

Process and reshape balances CSV exports from the Brazilian Central Bank (Bacen) downloaded via get_balance_sheets().

Description

tidy_balance_sheets reads raw CSV export files produced by the BCB and downloaded via get_balance_sheets(), normalizes filenames, locates the header row, imports rows matching a specific document number, cleans column names, pivots account balances so that each account becomes a column and each row corresponds to an institution/date, and optionally writes per-institution-type CSVs.

Usage

tidy_balance_sheets(path_raw, out_dir, doc_filter = 4010, save = TRUE)

Arguments

Details

Behavior and implementation notes:

• Filenames are first normalized by removing all underscores. If a target filename after normalization already exists, the function aborts to avoid overwriting files.

• The function extracts year/month and an institution type token from the file basename by assuming the first six characters are YYYYMM and the remaining characters (without the ".CSV") represent the type.

• For each file the function reads the file as text and attempts to locate the header row by scanning lines until it finds a row that contains (case-insensitive) tokens matching:

  • "DOCUMENTO" (or "DOCUMENTOS"),

  • "CNPJ",

  • and "DATA BASE" (variants matched by regex such as "DATA_BASE" or "#DATA_BASE"). The delimiter for that header line is heuristically detected among semicolon (";"), comma (","), or whitespace. For whitespace-delimited data the function uses read.table's default behavior.

• After locating the header, the table is read with utils::read.table using header = TRUE, the detected separator, latin1 encoding, and check.names = FALSE. Rows where the DOCUMENTO column equals doc_filter are kept.

• Column names are cleaned via janitor::clean_names() before the wide pivot. The function expects at least the following cleaned column names to be present: conta, saldo, and data. The pivot uses the id columns (data, documento, cnpj, nome_instituicao), conta as names and saldo as values.

• If save = TRUE each resulting data.frame is written to CSV using readr::write_csv() to the path returned by output_filename(type_inst) (wrapped with out_dir).

• The function will stop with informative errors in several situations: missing CSVs in path_raw, failure to find a header line with the required tokens, missing required columns after import/cleaning, or failure to rename files when removing underscores.

Value

A named list of data.frames (one element per unique institution type detected in the filenames). Each data.frame has one row per unique combination of (data, documento, cnpj, nome_instituicao) and one column per account (the "conta" values) with balances populated from the "saldo" column.

Note

The function prints a message reminding that the numeric values in the balance sheets are not adjusted for inflation. See: https://www.bcb.gov.br/estabilidadefinanceira/balancetesbalancospatrimoniais

Examples

# First, download balance sheets
get_balance_sheets(
  institution = "BANCOS",
  months = 12,
  first_year = 2023,
  final_year = 2023,
  out_dir = tempdir(),
  overwrite = FALSE
)

# Now, tidy the files
# Do not write outputs
tidy_balance_sheets(
  path_raw = tempdir(),
  out_dir = tempdir(),
  doc_filter = 4010,
  save = FALSE
)

# Write outputs
tidy_balance_sheets(
  path_raw = tempdir(),
  out_dir = tempdir(),
  doc_filter = 4016,
  save = TRUE
)

Process and unify institution CSV exports from the Brazilian Central Bank (Bacen) downloaded via get_institutions().

Description

This function reads and processes financial institutions data from the Brazilian Central Bank (Bacen) files that were previously downloaded using the get_institutions() function. It takes a directory path containing the institution files, processes them, and optionally saves the output to a specified directory.

Usage

tidy_institutions(path_dir, out_dir, verbose = TRUE)

Arguments

Value

A list of data.frames, where each element corresponds to a processed institution file. The names of the list elements typically correspond to institution identifiers or file names.

Examples

# First, download institution data
 get_institutions(
  institution = "COOPERATIVAS",
  start_date = "202311",
  end_date = "202312",
  out_dir = tempdir()
)
# Process institution files from a directory
institutions <- tidy_institutions(
  path_dir = tempdir(),
  out_dir = tempdir(),
  verbose = TRUE
)