Package {cagedr}

Title:	Access Novo CAGED Microdata from the Brazilian Ministry of Labour
Version:	0.1.0
Description:	Download and read the public, non-identified microdata of the Novo CAGED (Cadastro Geral de Empregados e Desempregados), the monthly registry of formal employment movements published by the Brazilian Ministry of Labour and Employment through the PDET FTP server ftp://ftp.mtps.gov.br/pdet/microdados/. Lists the reference months available on the server, downloads the three monthly files (movements declared on time, declared late, and exclusions) with an idempotent local cache, and reads the national 7z archives as a stream, filtering by state and selecting columns before anything is kept in memory, so that a single state can be extracted without loading the full national file. Also provides the official record layout and a helper to consolidate admissions, separations and net balance by reference month.
License:	MIT + file LICENSE
Encoding:	UTF-8
Language:	en-US
Depends:	R (≥ 4.1.0)
Imports:	archive (≥ 1.1.0), cli (≥ 3.6.0), curl (≥ 5.0.0), readr (≥ 2.1.0), rlang (≥ 1.1.0), stringi (≥ 1.7.0), tibble (≥ 3.2.0)
Suggests:	dplyr, knitr, rmarkdown, testthat (≥ 3.0.0), withr
SystemRequirements:	libarchive (via the 'archive' package)
Config/testthat/edition:	3
VignetteBuilder:	knitr
URL:	https://github.com/StrategicProjects/cagedr, https://strategicprojects.github.io/cagedr/
BugReports:	https://github.com/StrategicProjects/cagedr/issues
Config/roxygen2/version:	8.0.0
NeedsCompilation:	no
Packaged:	2026-09-22 12:05:26 UTC; leite
Author:	Andre Leite [aut, cre], Marcos Wasiliew [aut], Hugo Vasconcelos [aut], Carlos Amorim [aut], Diogo Bezerra [aut], Júlia Nascimento Barreto [aut]
Maintainer:	Andre Leite <leite@castlab.org>
Repository:	CRAN
Date/Publication:	2026-09-30 12:40:14 UTC

cagedr: Access Novo CAGED Microdata from the Brazilian Ministry of Labour

Description

Download and read the public, non-identified microdata of the Novo CAGED (Cadastro Geral de Empregados e Desempregados), the monthly registry of formal employment movements published by the Brazilian Ministry of Labour and Employment through the PDET FTP server <ftp://ftp.mtps.gov.br/pdet/microdados/>. Lists the reference months available on the server, downloads the three monthly files (movements declared on time, declared late, and exclusions) with an idempotent local cache, and reads the national 7z archives as a stream, filtering by state and selecting columns before anything is kept in memory, so that a single state can be extracted without loading the full national file. Also provides the official record layout and a helper to consolidate admissions, separations and net balance by reference month.

Author(s)

Maintainer: Andre Leite leite@castlab.org (ORCID)

Authors:

• Andre Leite leite@castlab.org (ORCID)

• Marcos Wasiliew marcos.wasiliew@sepe.pe.gov.br

• Hugo Vasconcelos hugo.vasconcelos@ufpe.br (ORCID)

• Carlos Amorim carlos.agaf@ufpe.br (ORCID)

• Diogo Bezerra diogo.bezerra@ufpe.br (ORCID)

• Júlia Nascimento Barreto juliabarreto@gd.seplag.pe.gov.br

See Also

Useful links:

• https://github.com/StrategicProjects/cagedr

• https://strategicprojects.github.io/cagedr/

• Report bugs at https://github.com/StrategicProjects/cagedr/issues

List the reference months published on the PDET/MTE FTP server

Description

Queries the public FTP server of the Ministry of Labour and Employment and returns the reference months (AAAAMM) of the Novo CAGED that are currently published, with the date each folder was last modified. The Ministry publishes a reference month around the end of the following month, and occasionally re-publishes earlier months.

Usage

caged_available(year = NULL, timeout = 30, verbose = NULL)

Arguments

Value

A tibble with one row per reference month and columns period (integer AAAAMM), year, month, modified (POSIXct, folder modification time on the server) and url (the folder URL). Sorted from the most recent to the oldest month. Returns an empty tibble, with a warning, when the server cannot be reached.

See Also

caged_download() to fetch the files of a month, caged_periods() to build a sequence of months offline.

Examples

# Requires network access to ftp.mtps.gov.br
months <- tryCatch(caged_available(year = 2026), error = function(e) NULL)
if (!is.null(months)) head(months)

Consolidate admissions, separations and net balance

Description

Applies the accounting rule of the Novo CAGED to a set of records read with caged_read() or caged_fetch() and aggregates them. Movements declared on time (MOV) and late (FOR) count with their own sign; exclusions (EXC) cancel a previously declared movement, so their saldomovimentacao is inverted before summing. The aggregation is always by competenciamov, the reference month of the movement, which is what the Ministry's published totals use.

Usage

caged_balance(data, by = NULL)

Arguments

Details

Because FOR and EXC archives of month M carry records of earlier months, the balance of a given month keeps changing as later archives are published. To reproduce the Ministry's figure for a month, read every archive published up to the date of interest.

Value

A tibble with the grouping columns and admissions (records with positive sign after the exclusion rule), separations (negative sign), net (admissions - separations) and records (number of records aggregated). When the data contain salario, also admission_salary (sum of the salaries of the admissions) and mean_admission_salary.

Examples

f <- system.file("extdata", "CAGEDMOV202301_sample.7z", package = "cagedr")
x <- caged_read(f, verbose = FALSE)
caged_balance(x, by = "uf")

Remove archives from the cache

Description

Remove archives from the cache

Usage

caged_cache_clear(period = NULL, cache_dir = NULL)

Arguments

Value

Invisibly, the number of files removed.

Examples

caged_cache_clear()

Cache directory used by cagedr

Description

Downloaded archives are stored in a local cache so that a reference month is never downloaded twice. The location is resolved in this order:

Usage

caged_cache_dir(cache_dir = NULL)

Arguments

Details

1. the cache_dir argument;

2. the CAGEDR_CACHE_DIR environment variable;

3. the cagedr.cache_dir R option;

4. a session-scoped folder under tempdir(), which R removes when the session ends.

Set one of the first three to keep the archives between sessions. Files published by the Ministry are large (about 55 MB per month) and change only when a month is re-published, so a persistent cache is recommended for repeated work.

Value

The cache directory path, created if needed.

Examples

caged_cache_dir()

# For a persistent cache, set the environment variable (for instance in
# your .Renviron). Here a temporary folder is used and the previous value
# is restored afterwards.
old <- Sys.getenv("CAGEDR_CACHE_DIR", unset = NA)
Sys.setenv(CAGEDR_CACHE_DIR = file.path(tempdir(), "caged-cache"))
caged_cache_dir()
if (is.na(old)) Sys.unsetenv("CAGEDR_CACHE_DIR") else Sys.setenv(CAGEDR_CACHE_DIR = old)

List the archives currently in the cache

Description

List the archives currently in the cache

Usage

caged_cache_list(cache_dir = NULL)

Arguments

Value

A tibble with columns path, period, file (MOV, FOR or EXC), size_bytes and modified.

Examples

caged_cache_list()

Download the monthly archives of the Novo CAGED

Description

Fetches the ⁠.7z⁠ archives of one or more reference months from the PDET/MTE FTP server into the local cache (see caged_cache_dir()). Archives already in the cache are not downloaded again unless force = TRUE.

Usage

caged_download(
  period,
  files = c("MOV", "FOR", "EXC"),
  cache_dir = NULL,
  force = FALSE,
  timeout = 900,
  verbose = NULL
)

Arguments

Details

Every reference month has up to three files, all national:

• MOV (⁠CAGEDMOV<AAAAMM>.7z⁠): movements declared on time for that month, the bulk of the data (about 55 MB compressed, 4 to 5 million records);

• FOR (⁠CAGEDFOR<AAAAMM>.7z⁠): movements declared late, which refer to earlier reference months (competenciamov < AAAAMM);

• EXC (⁠CAGEDEXC<AAAAMM>.7z⁠): exclusions, movements cancelled by the employer, also referring to earlier months.

The first months of the series (January to March 2020) have no FOR or EXC files; those are reported as not_found, not as errors.

Value

A tibble with one row per (period, file) and columns period, file, path (local path, NA when not available), status ("downloaded", "cached", "not_found" or "error") and url.

See Also

caged_read() to read a downloaded archive, caged_fetch() for download and read in one call.

Examples

# Requires network access; downloads about 1 MB (the EXC file is small).
res <- tryCatch(
  caged_download(202401, files = "EXC", cache_dir = tempdir()),
  error = function(e) NULL
)
res

Download and read Novo CAGED microdata in one call

Description

Convenience wrapper: caged_download() followed by caged_read() on every archive found, with the results stacked. Missing files (for example FOR/EXC in early 2020) are skipped with a message.

Usage

caged_fetch(
  period,
  uf = NULL,
  files = c("MOV", "FOR", "EXC"),
  columns = NULL,
  cache_dir = NULL,
  force = FALSE,
  types = TRUE,
  chunk_size = 500000L,
  timeout = 900,
  verbose = NULL
)

Arguments

Value

A tibble with the records of every archive read (see caged_read() for the columns), or an empty tibble when nothing was available. The attribute "download" holds the tibble returned by caged_download(), so that not_found and error files can be inspected.

Examples

# Requires network access. Pernambuco, one month, the three files:
pe <- tryCatch(
  caged_fetch(202401, uf = 26, cache_dir = tempdir(), verbose = FALSE),
  error = function(e) NULL
)
if (!is.null(pe)) table(pe$caged_file)

Record layout of the Novo CAGED microdata

Description

The columns of the monthly files, with the original (accented) name used by the Ministry, the normalized name returned by caged_read(), the type assigned when types = TRUE, the files in which the column appears and a short description. The official layout (the "Layout Nao-identificado Novo Caged Movimentacao" spreadsheet) is published in the same FTP folder as the data.

Usage

caged_layout()

Details

Two columns exist only in the exclusions file (EXC): competenciaexc and indicadordeexclusao.

Value

A tibble with columns column (normalized name), original (name in the file), type, files and description.

Examples

caged_layout()
subset(caged_layout(), files != "MOV, FOR, EXC")

Build a sequence of reference months

Description

Offline helper that expands a range of reference months in AAAAMM format. Useful to request several months from caged_download() or caged_fetch() without querying the server first.

Usage

caged_periods(from, to = from)

Arguments

Value

An integer vector of reference months, in increasing order.

Examples

caged_periods(202301, 202306)
caged_periods("202412")

Read a Novo CAGED archive as a stream

Description

Reads the .txt inside a monthly ⁠.7z⁠ archive without extracting it to disk and without loading the national file in memory: the text is decompressed as a stream and parsed in chunks, and each chunk is filtered by state and reduced to the requested columns before being kept. This is what makes it practical to extract one state (a few hundred thousand records) from a national file of several million records on a modest machine.

Usage

caged_read(
  path,
  uf = NULL,
  columns = NULL,
  types = TRUE,
  chunk_size = 500000L,
  verbose = NULL
)

Arguments

Value

A tibble with the selected records and columns, plus two columns added by the package: caged_file ("MOV", "FOR" or "EXC", detected from the archive name) and caged_period (the reference month of the archive, which for FOR and EXC differs from the competenciamov of the records). Column names are normalized: accents removed and lower case (competenciamov, municipio, salario). Returns an empty tibble when no record matches.

See Also

caged_layout() for the meaning of every column, caged_fetch() for download and read in one call.

Examples

# A small sample archive ships with the package (Pernambuco and Bahia rows).
f <- system.file("extdata", "CAGEDMOV202301_sample.7z", package = "cagedr")
x <- caged_read(f, verbose = FALSE)
dim(x)

# One state, a few columns
pe <- caged_read(f, uf = 26,
                 columns = c("competenciamov", "municipio", "saldomovimentacao", "salario"),
                 verbose = FALSE)
pe