Prepare Geographic Maps of Italian Territorial Units

Creates map-ready files by joining SITUAS data with ISTAT shapefiles for any territorial level. Exports multiple formats for R dashboards (RDS, GeoJSON) and Power BI (TopoJSON). Supports municipalities, provinces, regions, and geographic partitions.

prepare_territorial_maps(
  situas_data = NULL,
  pfun = NULL,
  territorial_level = "comuni",
  output_dir = "data",
  date = Sys.Date(),
  simplify = TRUE,
  tolerance = 0.001,
  keep_attributes = NULL,
  verbose = TRUE
)

Arguments

situas_data

data.table. SITUAS data to join with shapefile. If provided, this data will be used instead of downloading from the API. Must contain at least the appropriate join field for the territorial level. Default is NULL (download from API).

pfun

Integer or NULL. SITUAS report ID to download. Only used if situas_data is NULL. If both situas_data and pfun are NULL, defaults based on territorial_level. Also used for file naming. Common values:

  • 61: Current municipalities - Elenco comuni (default for "comuni")

  • 64: Provinces/UTS - Elenco Province/Uts (default for "province")

  • 68: Regions - Elenco Regioni (default for "regioni")

  • 71: Geographic partitions - Ripartizioni geografiche (default for "ripartizioni")

Use search_reports() to find other available reports.

territorial_level

Character string. Level of territorial unit to map. Must be one of: "comuni" (municipalities), "province" (provinces/metropolitan cities), "regioni" (regions), or "ripartizioni" (geographic partitions). Default is "comuni".

output_dir

Character string. Directory where output files will be saved. Defaults to "data". Directory will be created if it doesn't exist.

date

Date, POSIXct, or character string. Reference date for SITUAS data. Only used if situas_data is NULL and data is downloaded from API. Defaults to current date. The date determines which territorial configuration is returned (as territories change over time).

simplify

Logical. If TRUE (default), simplify geometries to reduce file size while preserving topology. Recommended for web mapping and dashboards.

tolerance

Numeric. Simplification tolerance (in map units, degrees for WGS84). Default is 0.001. Higher values = more simplification. Only used if simplify = TRUE and rmapshaper package is installed.

keep_attributes

Character vector. Attributes to keep in the output. Defaults to NULL (keep all attributes from SITUAS report). Set to a character vector to filter specific attributes. Adjust based on your chosen report and territorial level.

verbose

Logical. If TRUE (default), print progress messages.

Value

Invisibly returns a list with paths to the created files:

rds

Path to RDS file (merged R sf object with SITUAS attributes)

geojson

Path to GeoJSON file (for Leaflet/web mapping)

topojson

Path to TopoJSON file (for Power BI)

shapefile_rds

Path to RDS file (original sf shapefile before merge)

situas_rds

Path to RDS file (SITUAS data table before merge)

Details

Input Data:

  • Shapefile: data-raw/Limiti01012025_g.zip containing territorial boundaries in WGS84 projection for all levels

  • SITUAS data: Appropriate report based on pfun or territorial_level

Join Keys by Territorial Level:

  • comuni: PRO_COM - Province-municipality code (6 digits)

  • province: COD_UTS - Province/UTS code (3 digits)

  • regioni: COD_REG - Region code (2 digits)

  • ripartizioni: COD_RIP - Geographic partition code (1 digit)

Output Files:

  • RDS (merged): Fast loading in R, preserves merged sf object with SITUAS attributes. Best for R dashboards and analysis.

  • GeoJSON: Web standard, works with Leaflet and most mapping libraries. Human-readable format.

  • TopoJSON: Microsoft Power BI standard for Shape Map visual. More compact than GeoJSON.

  • Shapefile RDS: Original sf shapefile with geometries only (before merge with SITUAS). Useful for custom joins.

  • SITUAS RDS: SITUAS data table (before merge). Useful for separate attribute analysis.

File Sizes (approximate):

  • Comuni original: ~12 MB, simplified: ~1-2 MB

  • Province original: ~2 MB, simplified: ~0.5 MB

  • Regioni original: ~1 MB, simplified: ~0.3 MB

  • Ripartizioni original: ~0.5 MB, simplified: ~0.2 MB

  • TopoJSON is typically most compact

Using in Power BI:

  1. Open Power BI Desktop

  2. Insert > Shape Map visual

  3. Click on the visual, then Format > Shape > Map settings

  4. Click "+ Add map" and select the .json (TopoJSON) file

  5. Map your data using the appropriate join field

Setup

For better performance, extract the shapefile once before first use: source("data-raw/extract_shapefiles.R")

If not pre-extracted, the shapefile will be extracted to a temporary directory each time this function is called (slower but still works).

Examples

if (FALSE) { # \dontrun{
# 1. MUNICIPALITIES (default)
files <- prepare_territorial_maps()
# or explicitly
files <- prepare_territorial_maps(territorial_level = "comuni")

# 2. PROVINCES
files <- prepare_territorial_maps(
  territorial_level = "province",
  keep_attributes = c("COD_UTS", "DEN_UTS", "COD_REG", "DEN_REG")
)

# 3. REGIONS
files <- prepare_territorial_maps(
  territorial_level = "regioni",
  keep_attributes = c("COD_REG", "DEN_REG")
)

# 4. GEOGRAPHIC PARTITIONS
files <- prepare_territorial_maps(
  territorial_level = "ripartizioni",
  keep_attributes = c("COD_RIP", "DEN_RIP")
)

# Pass pre-downloaded SITUAS data (recommended for custom workflows)
regioni_data <- get_situas_tables(pfun = 68, date = "2025-01-01")
files <- prepare_territorial_maps(
  situas_data = regioni_data,
  territorial_level = "regioni"
)

# Use in Leaflet
library(leaflet)
map_sf <- readRDS(files$rds)
leaflet(map_sf) %>%
  addTiles() %>%
  addPolygons(popup = ~DEN_REG)  # or ~COMUNE, ~DEN_UTS, etc.

# Create maps for a specific date (auto-download)
files <- prepare_territorial_maps(
  territorial_level = "comuni",
  date = "2020-01-01"
)

# No simplification (larger files, more detail)
files <- prepare_territorial_maps(
  territorial_level = "province",
  simplify = FALSE
)

# Custom report with specific pfun
files <- prepare_territorial_maps(
  pfun = 73,  # Municipality characteristics
  territorial_level = "comuni",
  keep_attributes = NULL  # Keep all attributes
)

# Find available reports
reports <- search_reports()
print(reports[, .(pfun, title, analysis_type)])
} # }