get_balance_sheets: Download balance sheets from Brazilian Central Bank

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

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

institution	Character vector of institution types to download. Accepted values (case-insensitive): "BANCOS", "COOPERATIVAS", "CONSORCIOS" (Administradoras de consórcios), "CONGLOMERADOS" (Conglomerados financeiros), "SOCIEDADES", "BLOPRUDENCIAL" (Conglomerados Prudenciais), "COMBINADOS" (Combinados Cooperativos), "LIQUIDACAO" (Instituições em Regime Especial). The function maps these tokens to the type names used in the BCB URL.
months	Integer or integer vector specifying months to download. Values should be 1..12 (single values or vectors like c(6, 12)). When a month single-digit is provided it is zero-padded to two digits in filenames/URLs.
first_year	Integer, first year to download (inclusive). Defaults to 1993 (the oldest available balancete in the source).
final_year	Integer, last year to download (inclusive). Defaults to the previous calendar year.
out_dir	Character, directory where downloaded ZIP files (and extracted CSVs) will be written. The directory is created if it does not exist.
overwrite	Logical, whether to overwrite existing files in out_dir (default FALSE). If FALSE and a file already exists at the destination it is treated as a successful local result.

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.

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 banks and credit unions for June and December
# of 2022 and 2023
get_balance_sheets(
  institution = c("BANCOS", "COOPERATIVAS"),
  months = c(6, 12),
  first_year = 2022,
  final_year = 2023,
  out_dir = tempdir(),
  overwrite = FALSE
)

bacenR documentation built on Oct. 24, 2026, 1:07 a.m.