read_cnefe: Read CNEFE data for a given municipality

In cnefetools: Access and Analysis of Brazilian CNEFE Address Data

Read CNEFE data for a given municipality

Description

Downloads and reads the CNEFE CSV file for a given IBGE municipality code, using the official IBGE FTP structure. The function relies on an internal index linking municipality codes to the corresponding ZIP URLs. Data are returned either as an Arrow Table (default) or as an sf object with SIRGAS 2000 coordinates.

Usage

read_cnefe(
  code_muni = NULL,
  year = 2022,
  verbose = TRUE,
  cache = TRUE,
  cache_dir = NULL,
  output = c("arrow", "sf"),
  file = NULL
)

Arguments

code_muni	Integer. Seven-digit IBGE municipality code. Omit it when reading a local file through file.
year	Integer. The CNEFE data year. Currently only 2022 is supported. Defaults to 2022.
verbose	Logical; if TRUE, print informative messages about download, extraction, and reading steps.
cache	Logical; if TRUE, keep the downloaded data as a gzipped CSV in the cache folder (see cache_dir). If FALSE, a temporary file is used and removed after reading.
cache_dir	Character. Directory to use for cached downloads. If NULL (default), the CNEFETOOLS_CACHE_DIR environment variable is used when it is set, otherwise tools::R_user_dir() with which = "cache". Use this to point large downloads at a secondary drive or a shared volume.
output	Character. Output format. "arrow" (default) returns an arrow::Table, whereas "sf" returns an sf point object with coordinates built from LONGITUDE / LATITUDE in CRS 4674.
file	Character. Path to a CNEFE file already on disk, read instead of downloading. Accepts .zip as published by IBGE, .csv, .csv.gz and .parquet, which is what cnefe_export() writes. Mutually exclusive with code_muni, and it makes the function independent of the IBGE server.

Details

When output = "arrow" (default), the function does not perform any spatial conversion and simply returns the Arrow table. When output = "sf", the function converts the result to an sf point object using the LONGITUDE and LATITUDE columns, with CRS EPSG:4674 (SIRGAS 2000), keeping these columns in the final object (remove = FALSE).

Value

If output = "arrow", an arrow::Table containing all CNEFE records for the given municipality.

If output = "sf", an sf object with point geometry in EPSG:4674 (SIRGAS 2000), using the LONGITUDE and LATITUDE columns.

Caching

When cache = TRUE (the default), the municipality is downloaded once and kept as a gzipped CSV, so later calls, in this session or any other, reuse it instead of downloading again. The cache folder is cache_dir when given, otherwise the CNEFETOOLS_CACHE_DIR environment variable when set, otherwise tools::R_user_dir() with which = "cache".

When cache = FALSE, the file is stored in a temporary location and removed when the function exits.

The cache is meant to be cleared (see clear_cache_muni()). For a copy that stays put, use cnefe_export(). The "Cache and exported copies" article on the package website covers both.

See Also

cnefe_export() to write a municipality to a persistent, optimised file that this function can read back through file.

Examples

# Read CNEFE data as an Arrow table
cnefe <- read_cnefe(code_muni = 2929057, cache = FALSE)

# Read a local file instead, with no network access. overwrite = TRUE because
# cnefe_export() refuses to clobber an existing export by default.
path <- cnefe_export(2929057, path = tempdir(), cache = FALSE, overwrite = TRUE)
cnefe_local <- read_cnefe(file = path)

# Read as an sf spatial object
cnefe_sf <- read_cnefe(code_muni = 2929057, output = "sf", cache = FALSE)

cnefetools documentation built on Oct. 2, 2026, 1:08 a.m.