# Getting started with 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