Retrieve province-level deaths — get_ine

Retrieves, cleans, and validates Spanish annual death counts by province and sex from INE's Tempus3 JSON API, per the SHMD Protocol (Section 12, Step 1: "Death Count Assembly"). Fetches both an age-less table (for the national total and a national-vs-provincial reconciliation check) and an age-specific table (needed by compute_exposure() / compute_death_rates(), which require D(x,t), not just D(t)).

get_ine_deaths(
  table_id = 6545,
  age_table_id = 6547,
  n_periods = 100,
  use_cache = TRUE,
  force = FALSE,
  cache_dir = NULL
)

Arguments

table_id: INE table ID for the age-less (province + sex) series. Default 6545, confirmed for "Defunciones por lugar de residencia y sexo. Total nacional y provincias" (operation MNPD).
age_table_id: INE table ID for the age-specific series. Default 6547.
n_periods: Number of most recent years to fetch.
use_cache: Logical (default TRUE). If a previous call already cached a result for this table_id/age_table_id/n_periods combination, return it directly instead of re-fetching from INE — this function's live fetch (two tables) is one of the package's slowest. Set FALSE to always hit the network.
force: Logical (default FALSE). If TRUE, ignore any existing cache and re-fetch from INE, refreshing the cache afterwards.
cache_dir: Directory for cached data. The default NULL caches in a per-session directory under tempdir(): repeated calls in the same session reuse the first download, but nothing persists afterwards. Pass a directory, e.g. tools::R_user_dir("inedemogR", "cache"), for a cache that persists across sessions. A cache stores the parsed result as .rds; refresh it with force = TRUE. Results carry a provenance attribute (request, retrieval time in UTC, API, package version).

Value

list(data_provinces, data_national, qc, qc_age): data_provinces is age-specific (ine_code, nuts3_code, nuts2_code, province_name, year, age, female, male, total); data_national is Spain's age-less total.

Examples

if (FALSE) { # \dontrun{
# Not run: requires live network access to the INE API.
deaths <- get_ine_deaths(n_periods = 30)
deaths$data_provinces

# Re-fetch even if a cached copy exists:
deaths <- get_ine_deaths(n_periods = 30, force = TRUE)
} # }