tceper is an R client for the TCE-PE (Tribunal de Contas do
Estado de Pernambuco) Open Data API.
The package wraps 71 API endpoints into
user-friendly functions that accept snake_case parameter
names and return tibbles. A built-in catalog lets you discover
endpoints, inspect their input parameters and output fields — all
without leaving R.
|
⚠️ Warning The TCE-PE API ( sistemas.tcepe.tc.br) is geo-restricted
and only accessible from Brazilian IP addresses. If you are outside
Brazil, API queries will time out. The discovery functions
tce_catalog(), tce_params() and
tce_fields() work offline anywhere, as they read from the
built-in catalog.
|
|
❕️ Disclaimer This package acts as a wrapper for a Brazilian public API provided by the Tribunal de Contas do Estado de Pernambuco (TCE-PE), which is the institution responsible for the data. To maintain consistency with R package development standards, all wrapper functions are named in English. However, because the source API is natively in Portuguese, you will interact with Portuguese terms when passing arguments or parsing the responses. For example: you may use the function tce_state_revenues(), but you need to pass the parameters
in Portuguese, such as AnoReferencia = 2025. You can find
the original list of endpoints and their respective parameters in the official
API documentation.
|
# install.packages("remotes")
remotes::install_github("StrategicProjects/tceper")library(tceper)
# 1. Discover endpoints
tce_catalog()
tce_catalog(search = "contrat")
# 2. Inspect parameters and output fields
tce_params("Contratos")
tce_fields("Contratos")
# 3. Query (use snake_case or the original API names)
tce_contracts(codigo_efisco_ug = "510101")Before querying any endpoint, you can explore the built-in catalog directly from R.
tce_catalog()
#> # A tibble: 71 × 4
#> endpoint group title url
#> <chr> <chr> <chr> <chr>
#> 1 ReceitasEstaduais Receitas Receitas Estaduais …
#> 2 ReceitasMunicipais Receitas Receitas Municipais …
#> …
tce_catalog(search = "licit")tce_params("Contratos")
#> ── Contratos has 23 parameters: ──────────────────────────────
#> ℹ unidade_gestora, unidade_orcamentaria, esfera, …
#> ── Dictionary ────────────────────────────────────────────────
#> # A tibble: 23 × 5
#> api_name r_name required type description
#> <chr> <chr> <lgl> <chr> <chr>
#> 1 UnidadeGesto… unidade_gestor… FALSE character Unidade Gestora
#> …tce_fields("Contratos")Use snake_case names (from r_name) or the
original API names — both work:
# These are equivalent:
tce_contracts(codigo_efisco_ug = "510101")
tce_contracts(CodigoEfiscoUG = "510101")
# Add more filters
tce_contracts(codigo_efisco_ug = "510101", ano_contrato = "2025")When verbose = TRUE, the package prints the final API
URL and helper commands for inspecting the endpoint:
tce_contracts(codigo_efisco_ug = "510101", verbose = TRUE)
#> ℹ API URL: https://sistemas.tcepe.tc.br/DadosAbertos/Contratos!json?CodigoEfiscoUG=510101
#> ℹ To inspect this endpoint:
#> - Input parameters: tce_params("Contratos")
#> - Output fields: tce_fields("Contratos")Enable globally:
options(tceper.verbose = TRUE)All 71 wrapper functions cache results in memory, keyed by endpoint + parameters. Default TTL is 1 hour.
tce_contracts(codigo_efisco_ug = "510101") # hits the API
tce_contracts(codigo_efisco_ug = "510101") # cache hit (instant)
tce_contracts(codigo_efisco_ug = "510102") # different key → hits the API
tce_contracts(codigo_efisco_ug = "510101", cache = FALSE) # force fresh
tce_cache_info() # inspect cached entries
tce_cache_clear() # clear allThe package validates query parameters against the catalog. If you pass a parameter that doesn’t exist for that endpoint, it aborts with a helpful error listing the allowed parameters:
tce_contracts(xyz = "foo")
#> ✖ Unknown query parameter(s) for endpoint Contratos: xyz
#> ℹ Allowed parameters:
#> • unidade_gestora (UnidadeGestora)
#> • codigo_efisco_ug (CodigoEfiscoUG)
#> …| Option | Default | Description |
|---|---|---|
tceper.verbose |
FALSE |
Print final API URL on every call |
tceper.progress |
TRUE |
Show progress messages |
tceper.cache_ttl |
3600 |
Cache time-to-live in seconds |
options(
tceper.verbose = TRUE,
tceper.progress = FALSE,
tceper.cache_ttl = 7200
)The API returns at most 100,000 records per request. When this limit is reached, the package issues a warning. Use filters to narrow your query:
tce_municipal_expenditures(
codigo_municipio = "P113",
ano_referencia = "2025"
)If you prefer to pass API parameter names directly, use
tce_request():
tce_request("Contratos", CodigoEfiscoUG = "510101", AnoContrato = "2025")