datasus_fetch: Fetch DATASUS data in one step

In datasusr: Fast Access to Brazilian Public Health Data from 'DATASUS'

Fetch DATASUS data in one step

Description

A convenience wrapper that lists, downloads, and reads DATASUS files in a single call. Particularly useful for interactive / exploratory work.

Usage

datasus_fetch(
  source,
  file_type,
  year = NULL,
  month = NULL,
  uf = NULL,
  ...,
  bind = TRUE,
  include_prelim = TRUE,
  timeout = Inf,
  use_cache = TRUE,
  cache_dir = NULL,
  refresh = FALSE,
  overwrite = FALSE,
  verbose = TRUE
)

Arguments

source	Character vector of source codes.
file_type	Character vector of file type codes.
year	Integer vector of years.
month	Integer vector of months (required for monthly sources).
uf	Character vector of UF codes (required for UF-scoped sources).
...	Additional arguments forwarded to read_datasus_dbc() (e.g. select, col_types, parse_dates).
bind	Logical. When TRUE (the default), all files are row-bound into a single tibble. When FALSE, a list of tibbles is returned.
include_prelim	Logical. Include preliminary data trees (default TRUE).
timeout	Optional hard cap, in seconds, on each file transfer (default Inf, no cap); see datasus_download(). A finite value is also used for the FTP listing (otherwise 120 seconds).
use_cache	Logical. Reuse cached downloads (default TRUE).
cache_dir	Optional cache directory.
refresh	Logical. Force re-download even when a cached file exists (default FALSE). Forwarded to datasus_download().
overwrite	Logical. Re-download files that already exist at the destination (default FALSE). Forwarded to datasus_download().
verbose	Logical. Emit progress messages (default TRUE).

Details

Files that fail to download are skipped with a warning; if every download fails, an error is raised.

When the same file is available both as a final release and as a preliminary one (a SIM DO year that has just been consolidated, or a SINAN file requested together with its SINAN_P alias), only the final version is read, so rows are not duplicated. A final file that could not be confirmed on the FTP does not suppress a preliminary copy that is known to exist. Use datasus_list_files() and datasus_download() directly to work with both copies.

Value

A tibble (when bind = TRUE) or a named list of tibbles. List names are the file names; when the same file name comes from more than one FTP tree they are prefixed with the period (e.g. "prelim/DOPE2022.dbc").

Examples

tryCatch({
  # Fetch a small SIHSUS slice into tempdir() (network required).
  df <- datasus_fetch(
    source    = "SIHSUS",
    file_type = "RD",
    year      = 2024,
    month     = 1,
    uf        = "AC",
    select    = c("uf_zi", "ano_cmpt", "munic_res", "val_tot"),
    cache_dir = tempdir(),
    verbose   = FALSE
  )
}, error = function(e) message("FTP unavailable: ", conditionMessage(e)))

datasusr documentation built on Sept. 26, 2026, 1:08 a.m.