Get Available SITUAS Tables

Retrieves territorial unit data from the SITUAS (Sistema Informativo Territoriale delle Unità Amministrative e Statistiche) API. The function implements intelligent caching to minimize API calls and enable offline use. Cached data is stored locally and can be refreshed as needed.

This is a convenience wrapper around situas_get_report_data that provides caching functionality and defaults to retrieving the municipalities list (report ID 61).

get_situas_tables(
  pfun = 61,
  date = Sys.Date(),
  date_end = NULL,
  force_refresh = FALSE,
  max_age_hours = 24,
  verbose = TRUE
)

Arguments

pfun

Integer. Report ID to retrieve. Defaults to 61 (municipalities list). See list_available_reports for all available reports.

date

Date, POSIXct, or character string. The reference date for the report. For DATA type reports, this is the single date parameter. For PERIODO/ATTUALIZZAZIONE type reports, this is the start date. Defaults to current date.

date_end

Date, POSIXct, or character string. End date for PERIODO and ATTUALIZZAZIONE type reports. Required for these report types, ignored for DATA type reports. Default is NULL.

force_refresh

Logical. If TRUE, bypass cache and download fresh data from the API. If FALSE (default), use cached data if valid.

max_age_hours

Numeric. Maximum age of cache in hours before automatic refresh. Default is 24 hours. Ignored if force_refresh = TRUE.

verbose

Logical. If TRUE (default), print informative messages about cache status and download progress.

Value

A data.table containing the requested report data. The structure depends on the report ID requested. For the default municipalities report (ID 61), it includes columns such as:

COD_RIP

Geographic partition code

COD_REG

Region code

COD_UTS

Province/UTS code

PRO_COM

Municipality code (numeric)

PRO_COM_T

Municipality code (text)

COMUNE

Municipality name

DEN_REG

Region name

DEN_UTS

Province/UTS name

SIGLA_AUTOMOBILISTICA

Car registration code

COD_CATASTO

Cadastral code

Details

Get Available SITUAS Tables

Downloads the list of available territorial units from the SITUAS API. This function uses caching to enable offline use and reduce unnecessary API calls. By default, it retrieves the municipalities list (report ID 61).

Examples

if (FALSE) { # \dontrun{
# Get current municipalities list using cache if available
municipalities <- get_situas_tables()

# Force refresh from API
municipalities <- get_situas_tables(force_refresh = TRUE)

# Get municipalities as of a specific date
municipalities_2020 <- get_situas_tables(date = as.Date("2020-01-01"))

# Get provinces instead of municipalities
provinces <- get_situas_tables(pfun = 64)

# Get municipality changes over a period (PERIODO type report)
changes <- get_situas_tables(
  pfun = 99,
  date = as.Date("2020-01-01"),
  date_end = as.Date("2025-01-01")
)

# Use cached data up to 48 hours old
municipalities <- get_situas_tables(max_age_hours = 48)

# Suppress messages
municipalities <- get_situas_tables(verbose = FALSE)
} # }