An end-to-end ObrasGov workflow
In obrasgovr: Access the 'ObrasGov' Open Data API

knitr::opts_chunk$set(collapse = TRUE, comment = "#>")

library(obrasgovr)

This vignette develops a reproducible workflow for answering a concrete question: which active infrastructure projects in Pernambuco are represented in ObrasGov, and what physical execution and contract records are associated with them?

API calls are shown but not executed during package builds. This keeps the vignette suitable for CRAN while leaving the examples ready to run in an interactive R session.

1. Define the query explicitly

Keep the filter values and retrieval limits in an object. This makes the scope easy to review and store with the result.

project_query <- list(
  uf_principal = "PE",
  situacao = "Em execução",
  page_size = 200,
  all_pages = TRUE,
  page_limit = 5
)

project_query

Before sending the request, confirm that the chosen filters exist:

available_project_filters <- list_filters("projects")$filter
requested_filters <- c("uf_principal", "situacao")

all(requested_filters %in% available_project_filters)

2. Retrieve the project table

Use rlang::exec() to pass a named list of arguments to get_projects().

projects <- rlang::exec(get_projects, !!!project_query)

projects |>
  dplyr::select(
    id_projeto_investimento,
    desc_nome,
    situacao,
    dt_inicial_prevista,
    dt_final_prevista
  )

Always inspect the metadata after a limited multi-page request. If pages_retrieved equals page_limit while total_pages is larger, the result is intentionally incomplete.

project_metadata <- result_metadata(projects)

project_metadata[c(
  "total_items",
  "total_pages",
  "pages_retrieved",
  "retrieved_at"
)]

3. Choose project identifiers

Related endpoint queries should be limited to the projects needed for the analysis. The example below uses the first ten unique identifiers.

project_ids <- projects |>
  dplyr::distinct(id_projeto_investimento) |>
  dplyr::slice_head(n = 10) |>
  dplyr::pull(id_projeto_investimento)

project_ids

4. Retrieve related records

Map over identifiers and combine the returned tibbles. Each request is narrow and its relationship to the project table is explicit.

physical_execution <- project_ids |>
  purrr::map(function(project_id) {
    get_physical_execution(
      id_projeto_investimento = project_id,
      all_pages = TRUE,
      page_limit = 5
    )
  }) |>
  purrr::list_rbind()

The same pattern retrieves contracts:

contracts <- project_ids |>
  purrr::map(function(project_id) {
    get_contracts(
      id_projeto_investimento = project_id,
      all_pages = TRUE,
      page_limit = 5
    )
  }) |>
  purrr::list_rbind()

For a financial analysis, replace get_contracts() with get_commitments(). Feasibility studies and project status histories follow the same pattern.

5. Join project attributes to related records

The following local example demonstrates the join without contacting the API. Its column names mirror the ObrasGov response fields used above.

projects_example <- tibble::tibble(
  id_projeto_investimento = c("100.00-01", "200.00-02"),
  desc_nome = c("School renovation", "Health unit construction"),
  situacao = c("Em execução", "Em execução")
)

execution_example <- tibble::tibble(
  id_projeto_investimento = c("100.00-01", "200.00-02"),
  percentual_execucao_fisica = c(72.5, 35.0),
  dt_atualizacao_execucao = as.Date(c("2026-06-30", "2026-07-10"))
)

contracts_example <- tibble::tibble(
  id_projeto_investimento = c("100.00-01", "100.00-01", "200.00-02"),
  id_contrato = c(11L, 12L, 21L),
  valor_global_contrato = c(1200000, 300000, 2450000)
)

Join execution data one row per project:

project_execution <- projects_example |>
  dplyr::left_join(
    execution_example,
    by = "id_projeto_investimento"
  )

project_execution

Contracts form a one-to-many relationship. Summarize them before joining when the desired result is one row per project:

contract_summary <- contracts_example |>
  dplyr::group_by(id_projeto_investimento) |>
  dplyr::summarise(
    contract_count = dplyr::n(),
    total_contract_value = sum(valor_global_contrato, na.rm = TRUE),
    .groups = "drop"
  )

analysis_table <- project_execution |>
  dplyr::left_join(
    contract_summary,
    by = "id_projeto_investimento"
  )

analysis_table

6. Preserve provenance

Save data together with the original query, pagination metadata, package version, retrieval time, and source update timestamp.

provenance <- list(
  query = project_query,
  project_metadata = result_metadata(projects),
  source_updated_at = get_last_update(),
  package_version = utils::packageVersion("obrasgovr"),
  saved_at = Sys.time()
)

saveRDS(
  list(
    projects = projects,
    physical_execution = physical_execution,
    contracts = contracts,
    provenance = provenance
  ),
  "obrasgovr-pe-workflow.rds"
)