Getting started with tceper • tceper

Note — Code chunks in this vignette are shown but not executed at build time (eval = FALSE). The TCE-PE API host (sistemas.tcepe.tc.br) only accepts connections from Brazilian IP addresses, so requests would fail on CRAN check machines and on most CI runners outside Brazil. Run the snippets interactively from a Brazilian network to reproduce the outputs. The discovery functions (tce_catalog(), tce_params(), tce_fields()) work offline anywhere.

Overview

tceper is an R client for the TCE-PE (Tribunal de Contas do Estado de Pernambuco) Open Data API.

The package wraps the official endpoints into user-friendly functions that:

accept snake_case arguments (mapped to the API’s expected query names), and
return tibbles (with optional snake_case output column names).

Installation

# install.packages("remotes")
remotes::install_github("StrategicProjects/tceper")

Load the package

library(tceper)

Explore endpoints before querying

List endpoints

tce_catalog()

Filter by keyword:

tce_catalog(search = "contrat")

Inspect input parameters

tce_params("Contratos")

Inspect output fields

tce_fields("Contratos")

Quick queries

Municipalities

The Municipios endpoint is exposed as tce_municipalities().

tce_municipalities()

You can filter by state (UF) or by municipality name. Accented Portuguese characters work as-is – the package transcodes UTF-8 input to the Latin-1 encoding the API expects:

tce_municipalities(unidadefederativa = "PE")
tce_municipalities(municipio = "Recife")
tce_municipalities(municipio = "São José da Coroa Grande")

Contracts

tce_contracts(codigo_efisco_ug = "510101")

You can add additional filters. Use tce_params("Contratos") to see what is allowed.

tce_contracts(codigo_efisco_ug = "510101", ano_contrato = "2025")

Suppliers

The Fornecedores endpoint is exposed as tce_suppliers().

tce_suppliers(cpfcnpj = "25173110000186")
tce_suppliers(nome = "eireli")

Verbose mode (recommended while exploring)

When verbose = TRUE, the package prints:

the final API URL, and
helper commands to inspect inputs/outputs for the endpoint.

tce_bids(anomodalidade = "2025", verbose = TRUE)

Keeping original output field names

By default, output columns are converted to snake_case. To keep the original names from the API:

tce_municipalities(clean_names = FALSE)

Handling the 100,000-record limit

The API returns at most 100,000 records per request. When this limit is reached, tceper issues a warning.

To work around this, apply filters to narrow your query:

# Avoid unfiltered requests that may hit the 100k limit:
# tce_municipal_expenditures()

# Choose a municipality code:
library(dplyr)
library(stringr)

tce_municipalities() |>
  filter(str_detect(municipio, "Pesqueira")) |>
  glimpse()
# Rows: 1
# Columns: 5
# $ codigoibge        <chr> "2610905"
# $ codigo            <chr> "P113"
# $ unidadefederativa <chr> "PE"
# $ municipio         <chr> "Pesqueira"
# $ codigosagres      <chr> "5408"

# Filter by municipality and year:
tce_municipal_expenditures(
  codigo_municipio = "P113", # Pesqueira
  ano_referencia   = "2025"
)

Direct access to any endpoint

If you prefer to call an endpoint directly, use tce_request() and pass the API query names (as shown by tce_params()):

tce_request("Contratos", CodigoEfiscoUG = "510101", AnoContrato = "2025")

Cache

All wrapper functions cache results in memory. The default TTL is 1 hour.

tce_contracts(codigo_efisco_ug = "510101")  # hits the API
tce_contracts(codigo_efisco_ug = "510101")  # instant (from cache)

# Bypass cache
tce_contracts(codigo_efisco_ug = "510101", cache = FALSE)

# Inspect and manage
tce_cache_info()
tce_cache_clear()

You can change the TTL globally:

options(tceper.cache_ttl = 7200)  # 2 hours