tesouror

tesouror provides a unified R interface to the Brazilian National Treasury (Tesouro Nacional) open data APIs. It covers five major data sources:

All functions return tidy tibbles and have both Portuguese (matching API parameter names) and English aliases.

Installation

# From CRAN (when available):
install.packages("tesouror")

# Development version:
# remotes::install_github("StrategicProjects/tesouror")

Quick start

library(tesouror)

# List government entities
entes <- get_entes()

# RREO for Tocantins
rreo <- get_budget_report(
  fiscal_year = 2022, period = 6, report_type = "RREO",
  appendix = "RREO-Anexo 01", sphere = "E", entity_id = 17
)

# Federal government active staff costs (always filter by org AND month!
# the CUSTOS backend is slow; year-wide queries often hit HTTP 504)
custos <- get_costs_active_staff(
  year = 2023, month = 6,
  org_level1 = 244, org_level2 = 249  # MEC > INEP
)
# If pagination fails mid-way the package returns a partial result;
# check `attr(custos, "partial")` and `attr(custos, "last_page_error")`.

# Constitutional transfers (codes are Treasury-internal, NOT IBGE!)
estados <- get_tc_states()
pe <- estados$codigo[estados$nome == "Pernambuco"]
tc <- get_tc_by_state(state_code = pe, year = 2023)

# Public debt requests for PE
pvl <- get_debt_requests(state = "PE")

# SIORG: look up organization codes for CUSTOS queries
orgaos <- get_siorg_organizations(power_code = 1, sphere_code = 1)
# Use orgaos$codigo_unidade as org_level1 in get_costs_active_staff()

# SIOPE: education spending data
indicadores <- get_siope_indicators(year = 2023, period = 6, state = "PE")

# Clear the cache if needed
tesouror_clear_cache()

Features

• Bilingual: Portuguese and English function/parameter names
• Caching: In-memory cache avoids repeated API calls
• Pagination: Automatic handling of multi-page responses with progress
• verbose mode: Print full API URLs for debugging (verbose = TRUE or options(tesouror.verbose = TRUE))
• page_size control: Tune rows per page for speed vs. stability
• Clean output: janitor::clean_names() ensures consistent snake_case columns
• Friendly errors: Retries with informative messages; NA validation on required params
• Tidy output: All results are tibbles

Migrating from siconfir

tesouror is a superset of siconfir. All SICONFI functions work exactly the same. The cache-clearing function is now tesouror_clear_cache():

tesouror_clear_cache()

Documentation

See the package website at https://strategicprojects.github.io/tesouror/ for full documentation and vignettes.

Architecture

API Reference

SICONFI — Fiscal Reports

https://apidatalake.tesouro.gov.br/ords/siconfi/tt/

Provides fiscal reports (RREO, RGF, DCA), accounting matrices (MSC), and a government entity registry. Maintained by STN (Secretaria do Tesouro Nacional).

CUSTOS — Federal Government Costs

https://apidatalake.tesouro.gov.br/ords/custos/tt/

Cost data for active/retired staff, pensioners, depreciation, transfers, and other costs. Broken down by organization hierarchy (SIORG codes) and demographics.

Warning: The CUSTOS API is slow. Always filter by organizacao_n1

• organizacao_n2 (or org_level1 + org_level2) and by mes /

month to avoid HTTP 504 timeouts. Use max_rows for quick tests. Year-wide queries with no month filter routinely time out the upstream load balancer.

SADIPEM — Public Debt

https://apidatalake.tesouro.gov.br/ords/sadipem/tt/

Public debt verification letters (PVL), credit operations, payment schedules, exchange rates, and debt capacity results.

Transferências Constitucionais

https://apiapex.tesouro.gov.br/aria/v1/transferencias_constitucionais/custom/

Constitutional transfers (FPE, FPM, FUNDEB, etc.) to states and municipalities. Uses Treasury-internal codes (not IBGE codes) — use the dictionary functions to look them up.

SIORG — Organizational Structure

https://estruturaorganizacional.dados.gov.br/

Federal organizational structure: ministries, autarchies, foundations, and their internal hierarchy. Used as a dictionary to look up SIORG codes for CUSTOS API queries.

SIOPE — Education Spending

https://www.fnde.gov.br/olinda-ide/servico/DADOS_ABERTOS_SIOPE/versao/v1/odata/

Education spending data from FNDE/MEC: revenues, expenses, indicators, staff compensation, and declaration officials. Uses an OData-style API.

Tip: Use filter to narrow results on the server before downloading. Column names in filter/select/orderby must use the original API names (uppercase). Run a max_rows = 1 query and toupper(names(result)) to discover valid column names.

Common features (all APIs)

License

MIT