Access the 'Open Data API' of Pernambuco Court of Accounts.
tceper 
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](https://sistemas.tcepe.tc.br/DadosAbertos/Exemplo!listar). |
Installation
# install.packages("remotes")
remotes::install_github("StrategicProjects/tceper")
Quick start
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")
Explore the API
Before querying any endpoint, you can explore the built-in catalog directly from R.
1. Browse the catalog
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")
2. Inspect input parameters
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
#> …
3. Inspect output fields
tce_fields("Contratos")
4. Query
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")
Verbose mode
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)
Cache
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 all
Parameter validation
The 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)
#> …
Options
| 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
)
API limits
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"
)
Direct access
If you prefer to pass API parameter names directly, use tce_request():
tce_request("Contratos", CodigoEfiscoUG = "510101", AnoContrato = "2025")