tesouror tesouror logo

R-CMD-check

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

API Data Functions
SICONFI Fiscal reports (RREO, RGF, DCA, MSC), entities get_rreo(), get_rgf(), get_dca(), …
CUSTOS Federal government costs get_custos_pessoal_ativo(), …
SADIPEM Public debt & credit operations (PVL) get_pvl(), get_opc_*(), get_res_*()
SIORG Federal organizational structure (dictionary for CUSTOS) get_siorg_orgaos(), get_siorg_estrutura()
Transferências Constitutional transfers to states/municipalities get_tc_*()
SIOPE Education spending (FNDE/MEC) get_siope_dados_gerais(), get_siope_despesas(), …

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

❕ Disclaimer
This package acts as a wrapper for Brazilian public APIs provided by the Secretaria do Tesouro Nacional (STN), which is the institution responsible for the data. To maintain consistency with R package development standards, all wrapper functions are available with English names and English parameter names. However, because the source APIs are natively in Portuguese, some parameter values must still be passed in Portuguese (e.g., report_type = “RREO Simplificado”, appendix = “RREO-Anexo 01”), and response column names are in Portuguese (e.g., cod_ibge, exercicio, valor). For example: you may use get_budget_report(), but you need to pass values like appendix = “RREO-Anexo 01”. The original Portuguese-named functions (e.g., get_rreo(an_exercicio = 2022)) are also fully supported. You can find the original list of endpoints and their respective parameters in the official API documentation: SICONFI, CUSTOS, SADIPEM, SIORG, and Transferências Constitucionais, and SIOPE (FNDE/MEC).

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

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

tesouror package architecture — 6 APIs, 80 functions

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).

Detail Value
Pagination ORDS (hasMore/offset), automatic
Default page size Server default (5,000 rows)
Retries 5 attempts, progressive backoff (3s, 6s, 9s…)
max_rows Supported
Functions 18 (9 PT + 9 EN)

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.

Detail Value
Pagination ORDS (hasMore/offset), automatic
Default page size 500 rows (lowered from 1000 in 0.2.1: the backend timed out on broad queries)
Retries 5 attempts, progressive backoff (3s, 6s, 9s…)
max_rows Supported
Partial results When pagination fails mid-way, the package returns what was fetched with attr(result, "partial") = TRUE
SIORG code padding Automatic (244 → "000244")
Functions 12 (6 PT + 6 EN)

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.

Detail Value
Pagination ORDS (hasMore/offset), automatic
Default page size Server default (5,000 rows)
Retries 5 attempts, progressive backoff
max_rows Supported
Functions 14 (7 PT + 7 EN)

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.

Detail Value
Pagination None (single response)
Retries 5 attempts, progressive backoff
Multi-value params Accepts vectors (c(1,2)) or colon-separated strings ("1:2")
Functions 14 (7 PT + 7 EN)

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.

Detail Value
Pagination None (single response, JSON-based)
Retries 5 attempts, progressive backoff
Functions 6 (3 PT + 3 EN)

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.

Detail Value
Pagination OData ($top/$skip), automatic
Default page size 1,000 rows
Retries 5 attempts, progressive backoff
max_rows Supported
filter OData $filter for server-side filtering (e.g., "NOM_MUNI eq 'Recife'")
orderby OData $orderby for server-side sorting
select OData $select to choose specific columns
Functions 16 (8 PT + 8 EN)

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)

Feature Details
Caching In-memory per session. Clear with tesouror_clear_cache().
Retries 5 attempts with progressive backoff (3s, 6s, 9s, 12s, 15s) on HTTP 500/502/503/504/429 and connection failures. HTTP 400/404 are not retried.
verbose mode Per-call (verbose = TRUE) or global (options(tesouror.verbose = TRUE)). Prints full API URL for every request.
Column cleaning janitor::clean_names() applied to all responses (consistent snake_case).
Bilingual Every function has Portuguese (API-native) and English-named aliases.
Output Tidy tibbles with whitespace trimming.
Error messages Friendly, actionable messages with URL and hints. HTTP 400 errors suggest checking column names.

License

MIT