The hardware and bandwidth for this mirror is donated by dogado GmbH, the Webhosting and Full Service-Cloud Provider. Check out our Wordpress Tutorial.
If you wish to report a bug, or if you are interested in having us mirror your free-software or open-source project, please feel free to contact us at mirror[@]dogado.de.

Getting started with tesouror

Overview

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

API Data Prefix
SICONFI Fiscal reports (RREO, RGF, DCA, MSC), entities get_
CUSTOS Federal government costs get_custos_ / get_costs_
SADIPEM Public debt & credit operations get_pvl / get_opc_ / get_res_
SIORG Federal organizational structure (dictionary for CUSTOS) get_siorg_
Transferências Constitutional transfers to states/municipalities get_tc_
SIOPE Education spending (FNDE/MEC) get_siope_

All functions return tidy tibbles, use in-memory caching, and have both Portuguese-named (matching the API) and English-named versions.

Installation

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

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

Quick examples

library(tesouror)

# List all government entities
entes <- get_entes()

# Get RREO data for Tocantins (IBGE code 17)
rreo <- get_rreo(
  an_exercicio = 2022, nr_periodo = 6,
  co_tipo_demonstrativo = "RREO",
  no_anexo = "RREO-Anexo 01",
  co_esfera = "E", id_ente = 17
)

# Same query using English aliases
rreo <- get_budget_report(
  fiscal_year = 2022, period = 6,
  report_type = "RREO",
  appendix = "RREO-Anexo 01",
  sphere = "E", entity_id = 17
)

# Federal government costs (always filter by org to avoid slow queries!)
custos <- get_custos_pessoal_ativo(
  ano = 2023, mes = 6,
  organizacao_n1 = 244,  # MEC (auto-padded)
  organizacao_n2 = 249   # INEP
)

# Constitutional transfers (codes are Treasury-internal, NOT IBGE!)
estados <- get_tc_estados()
pe_code <- estados$codigo[estados$nome == "Pernambuco"]
tc <- get_tc_por_estados(p_estado = pe_code, p_ano = 2023)

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

Caching

All functions cache responses in-memory during your R session. This means repeated calls with the same parameters are instantaneous. To clear the cache:

tesouror_clear_cache()

Bilingual interface

Every function has two versions. The Portuguese version uses the exact API parameter names, while the English version uses descriptive English names:

# Portuguese (API-native)
get_dca(an_exercicio = 2022, id_ente = 17)

# English
get_annual_accounts(fiscal_year = 2022, entity_id = 17)

Both call the same endpoint and return the same data. See the vignette("siconfi"), vignette("custos"), vignette("sadipem"), vignette("siorg"), vignette("transferencias"), and vignette("siope") articles for API-specific details.

Debugging with verbose

Every function has a verbose parameter that prints the full API URL being called. This is useful for debugging or testing in a browser/curl:

# Per call:
get_costs_active_staff(year = 2023, month = 6, org_level1 = 244, verbose = TRUE)
#> ℹ API call: https://apidatalake.tesouro.gov.br/ords/custos/tt/pessoal_ativo?ano=2023&mes=6&organizacao_n1=000244&limit=1000

# Or globally for the session:
options(tesouror.verbose = TRUE)
get_entes()  # will print the URL
options(tesouror.verbose = FALSE)  # turn off

Controlling page size

ORDS-based APIs (SICONFI, CUSTOS, SADIPEM) return paginated results. The page_size parameter controls how many rows per page:

# CUSTOS defaults to 1000 rows/page (server default is only 250)
custos <- get_costs_active_staff(
  year = 2023, org_level1 = 244, org_level2 = 249
)

# Lower for quick tests:
custos_sample <- get_costs_active_staff(
  year = 2023, org_level1 = 244, org_level2 = 249,
  page_size = 100, max_rows = 200
)

# SICONFI/SADIPEM default to server's 5000 rows/page (fast)
entes <- get_entes()

Column names

All API responses are cleaned with janitor::clean_names() to ensure consistent snake_case column names (e.g., CO_IBGE becomes co_ibge).

API Reference

SICONFI — Fiscal Reports

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

Fiscal reports (RREO, RGF, DCA), accounting matrices (MSC), and entity registry. Maintained by STN. ORDS pagination (hasMore/offset) with server default of 5,000 rows/page. 18 functions (9 PT + 9 EN).

CUSTOS — Federal Government Costs

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

Cost data for active/retired staff, pensioners, depreciation, transfers, and other costs. ORDS pagination with default of 1,000 rows/page (server default of 250 is too slow; 5,000 causes timeouts). SIORG codes are auto-padded (244 → "000244"). 12 functions (6 PT + 6 EN).

Warning: Always filter by organization level (organizacao_n1 + organizacao_n2) to avoid downloading hundreds of thousands of rows.

SADIPEM — Public Debt

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

PVL (public debt verification letters), credit operations, payment schedules, exchange rates, and debt capacity. ORDS pagination with server default of 5,000 rows/page. 14 functions (7 PT + 7 EN).

Transferências Constitucionais

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

Constitutional transfers (FPE, FPM, FUNDEB, etc.). No pagination (single response). Accepts vectors (c(1,2)) or colon-separated strings ("1:2"). Uses Treasury-internal codes, not IBGE. 14 functions (7 PT + 7 EN).

SIORG — Organizational Structure

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

Federal organizational structure: ministries, autarchies, foundations. Used as a dictionary for CUSTOS organization codes. No pagination. 6 functions (3 PT + 3 EN).

SIOPE — Education Spending

Base URL: 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. OData pagination ($top/$skip) with default of 1,000 rows/page. Supports server-side filter (OData $filter), orderby, and select. 16 functions (8 PT + 8 EN).

Tip: Use filter = "NOM_MUNI eq 'Recife'" to narrow results on the server. Column names in filter/select/orderby must use the original API names (uppercase). Run toupper(names(result)) on a max_rows = 1 query to discover them.

Common features (all APIs)

All 80 functions share these features:

These binaries (installable software) and packages are in development.
They may not be fully stable and should be used with caution. We make no claims about them.
Health stats visible at Monitor.