October 26, 2026
bacenR: R package for downloading and processing data from the Central Bank of Brazil
Ricardo Theodoro; Walter Mesquita Filho
DOI: 10.22167/2675-6528-202603428
Article derived from a Course Conclusion Work (TCC), with content based on the student’s original work and adapted to the editorial format of the E&S Magazine with the support of the ResumeAI tool, an artificial intelligence solution developed by Instituto Pecege for textual synthesis and organization.
Summary
In academic research, data reliability and structure are crucial, but manually collecting information from the Central Bank of Brazil (Bacen) can be time-consuming and complex. The present study aimed to develop the bacenR package for the R language, facilitating the download and processing of Bacen data, including balance sheets, trial balances, registration data of financial institutions, normative acts, and credit portfolio information. The package development followed Wickham and Bryan’s (2023) guidelines for creating R packages, covering stages such as scope definition, function coding, testing, documentation, and maintenance. The functions were designed to download and organize data on regulations, balance sheets, and IFdata information. The bacenR package was made available on CRAN and GitHub, and its stable version was installed by 823 users. Its use demonstrated efficiency in collecting and processing large volumes of data with few lines of code. It was concluded that bacenR is a useful tool that optimizes research time by reducing the effort in data collection, allowing more dedication to analysis and democratizing access to financial information for researchers with less programming experience.
Keywords: Regulatory acts; Bacen; Trial balance; IFdata; Financial institutions.
1. Introduction
Academic research on banks and credit unions fundamentally depends on access to reliable, granular, and up-to-date financial data. This data is essential for investigating the efficiency, performance, risk, and competitiveness of these institutions within the national financial system. The relevance of the topic is growing, as indicated by the Coordination for the Improvement of Higher Education Personnel (CAPES), which recorded an expansion in the number of annual theses and dissertations on the subject, from 37 in 2010 to 64 in 2022.
Several studies have already shown the importance of using data from reliable sources to test hypotheses and propose solutions (Bath, 2023; Olmsted, 2024; Hackman et al., 2024). In this context, the Central Bank of Brazil (Bacen) plays a strategic role by publicly providing a huge amount of data. These range from historical series to specific statistics from different segments of the financial system, including commercial banks, credit cooperatives, non-bank financial institutions, and service points (Theodoro et al., 2021; Canassa et al., 2022; Bressan et al., 2023). This open data policy democratizes access to information and promotes methodological advances in academic research, making descriptive and inferential analysis with technical rigor possible.
However, despite the wide availability of these data, the collection and processing of information still represents a significant challenge for researchers, especially those with little experience in programming or automation. The manual process demands time, attention, human resources, and is subject to inconsistencies, duplications, and typing errors, especially when it comes to unifying multiple databases, handling distinct formats, and constantly updating regulatory requirements. Specialized literature indicates that the data preparation and cleaning stage can consume up to 80% of the analysis time, making it unfeasible to conduct large-scale studies efficiently without adequate tools (Paton, 2019; Santos et al., 2025).
In this context, the development of a specialized R package to download, process, and organize ready-to-analyze Bacen data emerges as an initiative with potential academic and social relevance. Such a tool automates collection and transformation routines, and a well-documented package, with a user manual and concrete examples, expands access for researchers with little technical experience, fostering innovative work and ensuring that data analysis is performed in a standardized and reliable manner. This allows the researcher to spend more time analyzing data than collecting it. Although packages like BacenAPI (Icaro et al., 2025), rbcb (Freitas, 2024), and BETS (Costa et al., 2018) already exist and demonstrate the need for open-source solutions for national economic and financial research, they focus on data such as IPCA, SELIC, GDP, and Government Debt, and do not cover all data available through Bacen. There is a gap for a package that downloads data such as financial institution balance sheets, organizes them for ease of use, and downloads the normative instructions issued by the Securities and Exchange Commission (CVM) and made available by Bacen.
Given the points presented and the need to fill this gap, the objective of this work was to create an R package, named bacenR, to download information about Normative Instructions that govern the regulation and supervision of financial institutions, their Balance Sheets and Trial Balances, information about the active credit portfolios of each institution, and data on the address of active financial institutions in each period, so that the obtained data are easily processed and organized.
2. Material and Methods
The research was characterized as applied in nature, with a methodological approach of developing a software package, specifically for the R language. The central objective was to create a tool, named bacenR, capable of automating the process of collection, treatment, and organization of financial and regulatory data made available by the Central Bank of Brazil (Bacen), aiming to facilitate academic analysis and reduce manual effort.
The methodology adopted was based on the guidelines of Wickham and Bryan (2023), who systematically describe the process of conception and development of packages in the R environment. Complementarily, the works of Grolemund (2014), Marwick et al. (2018a; 2018b), Silge (2018), Wickham (2021), and Wickham et al. (2023) were used as reference. These materials were essential for addressing principles of best practices in programming, reproducibility, testability, and code readability.
The package development occurred in sequential stages, according to the model proposed by Wickham and Bryan (2023). The phases included: 1) Initial development environment configurations; 2) Definition of package components, such as code and data; 3) Elaboration of metadata, covering description, dependencies, and license; 4) Rigorous testing of functionalities; 5) Detailed documentation; and 6) Continuous package maintenance.
As an initial step, the project scope was defined, including the language to be used, the main functionalities to be implemented, and the execution schedule. Subsequently, a “GitHub Project” was created to enhance development management, distribute tasks, track implementation progress, and plan the next work stages.
With the organizational structure established, the package coding phase began. The functions were designed to download the regulations published by the Central Bank of Brazil and their amendments, extract the full text of these regulations, obtain the balance sheets and trial balances of financial institutions, and process this data, preparing it for later analysis. The initial functions developed were `get_normative_data()`, `get_normative_txt()`, `get_balance_sheets()` and `tidy_balance_sheets()`.
Subsequently, the structural components of the package were analyzed, which consist of the source code, databases, directories, and bibliographic references, in order to ensure its internal consistency and coherence. Once this verification was completed, the metadata were elaborated, which included a detailed description of the package, its dependencies, and the definition of the usage license. For the operation of bacenR, the R environment needs to be version 4.1 or higher, and packages such as `dplyr`, `fs`, `glue`, `httr`, `janitor`, `jsonlite`, `lifecycle`, `purrr`, `readr`, `rlang`, `stringr`, `tibble`, `tidyr`, `tools`, `utils`, and `xml2` were used as dependencies.
With the final structure consolidated, the testing phase began. Each function was subjected to individual tests using the `testthat` and `devtools` packages, employing different parameters to verify the robustness and behavior of the code. Identified errors were iteratively corrected, implying adjustments in coding, documentation, and declared dependencies. After approval in all tests, including the “R CMD CHECK” executed through integration with “GitHub”, the formal documentation process began, with the help of the `usethis` package. All functions were described in detail, with the exposition of their objectives, parameters, expected results, and respective data sources, in order to ensure total transparency and comprehensibility to the end user.
With the final package, it was made available on “GitHub”, accompanied by a README.md file containing installation instructions, an explanation of how it works, and examples of the use of the implemented functions. The released version, named bacenR v0.1.0, was classified as a beta version. To expand the validation phase, the package was disseminated on social media, allowing for the collection of feedback to identify flaws, propose improvements, and define new functionalities to be incorporated.
After collecting feedback, the functions were adjusted and new functionalities were added, following user needs. These new functions aimed to collect data from IFdata on the active credit portfolios of financial institutions and the address of authorized institutions. The added functions were `get_ifdata_reports()`, `get_ifdata_registry()`, `get_institutions()`, and `tidy_institutions()`. After a series of tests and improvements, already in version 0.3.1, the package was submitted for evaluation by the “Comprehensive R Archive Network” (CRAN), the official repository for the R language, under the “General Public License” 3 (GPL-3.0) license. For the submission, a “vignettes” file was created with the package description and usage examples, in addition to a README.md on GitHub, which contains a brief presentation of the package, suggestions for similar packages, installation instructions, basic uses, a list of future tasks, author information, how to cite and support, and a guide for contributions.
3. Results and Discussion
The initial phase of the bacenR package development focused on creating an organized environment in “GitHub Projects”, following software project management best practices. This environment was structured to manage the “issues” (tasks or problems) that arose during the coding and documentation process. The organization allowed both developers and potential collaborators to track the progress of functionalities, check which tasks were in progress or completed, and identify gaps for new contributions. This collaborative approach is fundamental for open-source projects, encouraging community participation and improving the tool’s robustness.
In “GitHub Projects”, tasks were categorized by “Status” into “Todo”, “In Progress”, and “Done”, facilitating visual workflow tracking. Additionally, team management features were incorporated, such as “Priority”, “Size”, “Estimate”, “Start date”, and “End date”. These metrics not only assisted the maintainer in managing development but also served as a guide for coordinating a team of contributors, promoting transparency and efficiency in the package lifecycle.
The choice of English for the package was strategic, aiming to maximize the tool’s global reach and attract a broader user and contributor base. However, to ensure accessibility for Brazilian users, error messages and some instructions were translated into Portuguese. The parameters of each function were also described in Portuguese, which facilitates understanding and use of the package by researchers and professionals in Brazil, aligning with the objective of democratizing access to data from the Central Bank of Brazil.
The first functions developed, in version 0.1.0 of the package, included `get_normative_data()`, `get_normative_txt()`, `get_balance_sheets()`, and `tidy_balance_sheets()`. The `get_normative_data()` function was designed to download normative acts from Bacen, allowing searches by specific terms and within a date range. Complementarily, the `get_normative_txt()` function enabled the extraction of the full text of these normative acts from the `data.frame` generated by the previous function, providing detailed access to the regulatory content.
For financial data, the `get_balance_sheets()` function was implemented to download balance sheets and trial balances from financial institutions, with filtering options by year, month, and document type. Subsequently, the `tidy_balance_sheets()` function was developed to process and organize the downloaded balance sheets, preparing them for analysis. The internal documentation for each function, accessible directly within the R environment, describes the objective, data collection source, necessary parameters, and usage examples, ensuring clarity and ease of use for the user.
The license adopted for the package was the “General Public License” 3 [GPL-3.0], which ensures the freedom to use and distribute the package and its functions in other programs, as long as the distribution of these is also free. After the completion of tests and the guarantee of compliance with good practices for development in R, the package was made available on “GitHub”. A README.md file was created to accompany the package, providing a concise presentation, installation instructions, basic usage examples, and information on how to contribute.
The 0.1.0 version, classified as beta, was widely disseminated on social networks such as LinkedIn, Twitter/X, and Instagram, generating significant engagement. The posts received an average of 150 likes and 3,000 impressions or views, indicating a notable interest from the academic and professional public in facilitated access to this data. This initial dissemination was crucial for collecting valuable user feedback, which contributed to identifying flaws, suggesting improvements, and proposing new functionalities, demonstrating the package’s relevance to the community.
In response to the feedback received, version 0.3.0 of the package has been enhanced with the addition of four new functions. These include `get_ifdata_reports()` to download institutional IFdata report data, `get_ifdata_registry()` to obtain IFdata institutional registry data, `get_institutions()` to download registration data of institutions authorized by Bacen, and `tidy_institutions()` to process and organize this registration data. With these additions, the final version of the package now has a total of eight functions dedicated to data collection and processing, significantly expanding its capacity for accessing financial information.
After a series of tests and continuous improvements, the bacenR package, version 0.3.1, was submitted for evaluation by the “Comprehensive R Archive Network” (CRAN), the official repository for the R language. The package’s acceptance into CRAN represents an important milestone, granting it greater visibility and credibility within the scientific and technical community. For its formal publication, a “vignette” was created, a document that offers a detailed description of the package and practical usage examples, complementing the GitHub README.md and facilitating adoption by new users.
The installation of the stable version of the bacenR package is performed using the command `install.packages(“bacenR”)` in the R environment, as instructed in the updated README.md. This distinction between the stable CRAN version and the development version available on GitHub is important for users, ensuring they can choose the version best suited to their needs. The package’s directory structure, including source code files, documentation, tests, and vignettes, reflects R package development best practices, ensuring its organization and maintenance.
get_balance_sheets() and tidy_balance_sheets()
The `get_balance_sheets()` and `tidy_balance_sheets()` functions are designed to simplify access and organization of financial institutions’ balance sheets and trial balances. The `get_balance_sheets()` function allows downloading data by specifying institution types (such as “BANCOS”, “COOPERATIVAS”, “CONSORCIOS”), months (from 1 to 12), and a range of years (first and last year). The user can also define an output directory and choose to overwrite existing files. For example, it is possible to download the balance sheets of all credit cooperatives for December 2023.
After downloading, the `tidy_balance_sheets()` function comes into play to process and organize this data. It transforms raw balance sheets into a more analysis-friendly format, where each row represents an observation and each column a specific piece of information. In the practical example, credit union balance sheets for December 2023, filtered by code 4010, were downloaded and organized, resulting in a `tibble` with 800 rows and 145 columns, containing detailed information such as CNPJ, institution name, and various financial indicators. It is important to note that the values are not adjusted for inflation.
get_institutions() and tidy_institutions()
The `get_institutions()` and `tidy_institutions()` functions facilitate the retrieval and organization of financial institution registration data. The `get_institutions()` function allows downloading information about various types of financial institutions registered with Bacen, such as conglomerates, banks, cooperatives, and societies. Parameters include specifying the institution type, start and end dates in “YYYYMM” format, an output directory, and options to remove ZIP files after extraction and display progress messages.
After downloading, the `tidy_institutions()` function organizes registration data for analytical use. In the usage example, when downloading data from cooperatives for November and December 2023, the function returns variables such as CNPJ, institution name, address, municipality, state (UF), class, membership criterion, phone, and email. This standardized organization is crucial for research involving the analysis of the structure and location of financial institutions, enabling efficient comparisons and geographical mapping.
get_normative_data() and get_normative_txt()
The `get_normative_data()` and `get_normative_txt()` functions offer simplified access to the regulations issued by the Central Bank of Brazil. The `get_normative_data()` function requires only the desired search terms and a start and end date range to perform the search and download of normative acts. The results include variables such as title, type of regulation, number, subject, publication date, and information about linked regulations and updates.
The `get_normative_txt()` function complements the previous one, allowing the download of the full text of the normative acts found. Although these functions facilitate access to a vast repository of regulations, it is crucial to note that downloading texts can be a time-consuming process. Bacen imposes access limits, and the scope of a very extensive period or the use of many terms simultaneously can result in errors. It is therefore recommended to reduce the scope period in case of failures, optimizing the collection of regulatory data.
get_ifdata_reports and get_ifdata_registry
Finally, the `get_ifdata_reports()` and `get_ifdata_registry()` functions were developed to access IFdata data, which include institutional reports and records. The `get_ifdata_reports()` function allows downloading institutional reports by specifying the year, month, type of institution (such as prudential conglomerates, financial conglomerates, or individual institutions), and the type of report (summary, assets, liabilities, income statement, capital information, active credit portfolio by indexer, risk, geographic region, clients, individual and corporate entity type, borrower size, foreign exchange transactions). The function offers a wide range of options for detailed financial analysis.
The `get_ifdata_registry()` function allows downloading registry data from institutions present in IFdata, providing additional registration information. In the usage example, when downloading reports and registries for December 2024, the `get_ifdata_reports()` function returned 8,532 records with variables such as institution type, institution code, report name, and balance, while `get_ifdata_registry()` returned 5,752 records with institution code, date, institution name, municipality, and status. It is important to note that to interpret some columns, it is necessary to consult a dictionary available on the IFdata website, a feature that will be integrated into the package in future updates. A practical example demonstrated the ability to obtain 10 years of data on credit portfolios with a few lines of code, highlighting the tool’s efficiency.
Usage Tutorial
The release of the bacenR package on CRAN on 03/08/2026 and its subsequent use demonstrated significant community interest. By 04/09/2026, the package had registered 823 downloads, highlighting its relevance and acceptance among users. To further enhance accessibility, especially for those less familiar with R programming, a video tutorial was created and published on YouTube on 03/28/2026. This tutorial, which showcased the package and its functions, accumulated 288 views by 04/09/2026, reinforcing the demand for tools that simplify data collection and optimize research time.
Research possibilities
The bacenR package opens up a vast array of possibilities for research and data analysis in the financial sector. With the available functions, it is possible to investigate complex issues, such as the geographical distribution of the largest banks and credit unions, identifying which cities and states have a higher concentration of bank branches or new institutions. The tool allows for the analysis of the relationship between different types of institutions at the municipal level, the average age of institutions, and growth patterns in terms of the number of branches, assets, or volume of operations over time, both in specific quartiles and in determined regions.
Furthermore, bacenR enables the comparison of credit portfolios between banks and cooperatives, identifying similarities and differences that may vary by region or institution age. The integration of regulatory data allows for an investigation into how specific regulatory milestones can influence these data. These analyses are crucial for public policymakers, as they provide subsidies to direct regulation to locations and institutions that most need intervention, ensuring the sustainable development of the national financial system and consumer protection.
The development of the bacenR package proved to be a highly useful tool, enabling researchers and professionals to collect and process a wide range of data from the Central Bank of Brazil with just a few lines of code. This efficiency translates into significant time savings, which can be redirected from data collection to the analysis and interpretation of results. The positive reception on social media and the number of package installations confirm the community’s interest, especially among those with less programming experience, in democratizing access to financial information.
4. Conclusion
This study aimed to develop the bacenR package for the R language, with the purpose of optimizing the access, download, and processing of data from the Central Bank of Brazil, including balance sheets, trial balances, financial institution registration information, normative acts, and data on credit portfolios. It was verified that the package development followed good practices for creating R packages, resulting in the implementation of eight main functions that allowed the collection and organization of vast volumes of data with few lines of code. The tool’s efficiency in automating collection and processing routines was observed, which translated into significant time savings for researchers. The availability of bacenR on CRAN and GitHub, along with dissemination on social media and a video tutorial, generated expressive engagement, with 823 installations of the stable version, evidencing the relevance and acceptance of the tool by the academic and professional community. This contribution lies in democratizing access to complex financial information, allowing researchers, even with less programming experience, to dedicate more time to the analysis and interpretation of results.
Despite the robustness achieved, it was identified that the download process of normative texts can be time-consuming due to access limitations imposed by Bacen, suggesting the need for optimization for very extensive periods. It was also found that the interpretation of some columns in the IFdata data requires consulting an external dictionary, and the balance values are not adjusted for inflation, which represents current limitations. For future studies, it is recommended to improve the error and warning messages of the package, integrate a native dictionary for IFdata data, and develop new functions to expand information collection. Additionally, the creation of a Shiny interface could further simplify the use of the package for users without programming knowledge. bacenR, by facilitating access to granular data, opens up a vast range of possibilities for investigations into the geographical distribution of financial institutions, the comparison of credit portfolios, and the impact of regulatory milestones, providing valuable subsidies for public policies and the development of the national financial system.
Bibliographic References
Bath, 2023 [Referência completa não encontrada no documento original]
Bressan, V. G. F., Souza, G. H. D., Santos, M. H. S., & Braga, M. J. (2023). Cooperativas de crédito e competitividade no mercado financeiro brasileiro: uma análise das taxas de juros. Revista De Gestão E Organizações Cooperativas, 10(19), e68474. https://doi.org/10.5902/2359043268474
Canassa, B. J., Zancan, F., & de Moura Costa, D. R. (2022). Quadro Social e Ciclo de Vida de Cooperativas: Evidências em Cooperativas de Crédito Brasileiras. Contabilidade Gestão E Governança, 25(1), 43–59. https://doi.org/10.51341/1984-3925_2022v25n1a3
Costa Ferreira P, Speranza T, Costa J (2018). BETS: Brazilian Economic Time Series. https://doi.org/10.32614/CRAN.package.BETS
Freitas W (2024). rbcb: R Interface to Brazilian Central Bank Web Services. https://doi:10.32614/CRAN.package.rbcb
Grolemund, G. (2014). Hands-On Programming with R: Write Your Own Functions and Simulations. O’Reilly Media.
Hackman, L., Mack, P., & Ménard, H. (2024). Behind every good research there are data: What are they and their importance to forensic science. Forensic Science International: Synergy, 8, 100456. https://doi.org/10.1016/j.fsisyn.2024.100456
Icaro P, Sousa L, Ferreira da Silva F (2025). BacenAPI: Data Collection from the Central Bank of Brazil. https://doi.org/10.32614/CRAN.package.BacenAPI
Marwick, B., Boettiger, C., and Mullen, L. (2018a). “Packaging Data Analytical Work Reproducibly Using r (and Friends).” The American Statistician 72 (1): 80–88. https://doi.org/10.1080/00031305.2017.1375986.
Marwick, B., Boettiger, C., and Mullen, L. (2018b). “Packaging Data Analytical Work Reproducibly Using r (and Friends).” PeerJ Preprints 6 (March): e3192v2. https://doi.org/10.7287/peerj.preprints.3192v2.
Olmsted, J. (2024). Research reliability and validity: Why do they matter? Journal of Dental Hygiene, 98(6), 53–57.
Paton, N. (2019). Automating Data Preparation: Can We? Should We? Must We? In Proceedings of the 21st International Workshop on Design, Optimization, Languages and Analytical Processing of Big Data http://ceur-ws.org/Vol-2324/Paper00-InvTalk2-NPaton.pdf
Santos, A. G. V., Alves, J. J. M., Pinto, D. S. A., & Ferreira, P. C. A. (2025). A Importância Da Limpeza E Qualidade Na Análise De Dados: O Papel De Ferramentas Como O Power Bi. Revista Foco, 18(11), e10458. https://doi.org/10.54751/revistafoco.v18n11-083
Silge, J., Nash, J. C. and Graves, S. (2018). “Navigating the R Package Universe.” The R Journal 10 (2): 558-63. https://doi.org/10.32614/RJ-2018-058.
Theodoro, R., Bonacim, C. A. G., & de Moura Costa, D. R. (2021). Identificação de Ações Discricionárias do Gestor em Cooperativas de Crédito: Uma aplicação da Lei de Benford. Contabilidade Gestão E Governança, 24(3), 331-348. https://doi.org/10.51341/1984-3925_2021v24n3a5
Wickham, H. (2021). Mastering Shiny: Build Interactive Apps, Reports, and Dashboards Powered by R. O’Reilly Media.
Wickham, H., & Bryan, J. (2023). R Packages: Organize, Test, Document, and Share Your Code. O’Reilly Media.
Wickham, H., Cetinkaya-Rundel, M., & Grolemund, G. (2023). R for Data Science: Import, Tidy, Transform, Visualize, and Model Data. O’Reilly Media.
Article originating from the Final Course Project of the Specialization in Data Science and Analytics of the MBA USP/Esalq
To learn more about the course, click here and access the MBX Academy platform