Prepare Geographic Maps of Italian Territorial Units

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

prepare_comuni_maps(
  situas_data = NULL,
  pfun = NULL,
  output_dir = "data",
  date = Sys.Date(),
  simplify = TRUE,
  tolerance = 0.001,
  keep_attributes = c("PRO_COM", "PRO_COM_T", "COMUNE", "COD_REG", "DEN_REG", "COD_UTS",
    "DEN_UTS", "SIGLA_AUTOMOBILISTICA"),
  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 a PRO_COM column for joining. 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 to 61 (municipalities). Also used for file naming. Common values:

  • 61: Current municipalities - Elenco comuni

  • 64: Provinces/UTS - Elenco Province/Uts

  • 68: Regions - Elenco Regioni

  • 73: Municipality characteristics - Comuni caratteristiche

Use search_reports() to find other available reports.

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 common municipality attributes. Set to NULL to keep all attributes from the SITUAS report. Adjust based on your chosen report.

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 municipality boundaries in WGS84 projection

  • SITUAS data: Report 61 with current municipality codes and names

Join Key: Data is joined on PRO_COM code, which uniquely identifies each municipality.

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):

  • Original shapefile: ~12 MB

  • Simplified (tolerance=0.001): ~1-2 MB

  • TopoJSON: ~0.5-1 MB (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 PRO_COM or COMUNE field

Note

This function is now a wrapper around prepare_territorial_maps. For working with provinces, regions, or geographic partitions, use prepare_territorial_maps directly with the appropriate territorial_level parameter.

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{
# Basic usage - municipalities (default)
files <- prepare_comuni_maps()

# Pass pre-downloaded SITUAS data (recommended for custom workflows)
comuni_data <- get_situas_tables(pfun = 61, date = "2025-01-01")
files <- prepare_comuni_maps(situas_data = comuni_data)

# Provinces/UTS - download automatically
files <- prepare_comuni_maps(
  pfun = 64,
  keep_attributes = c("COD_UTS", "DEN_UTS", "COD_REG", "DEN_REG")
)

# Regions - using pre-downloaded data
regioni_data <- get_situas_tables(pfun = 68)
files <- prepare_comuni_maps(
  situas_data = regioni_data,
  keep_attributes = c("COD_REG", "DEN_REG")
)

# Use in Leaflet
library(leaflet)
comuni_sf <- readRDS(files$rds)
leaflet(comuni_sf) %>%
  addTiles() %>%
  addPolygons(popup = ~COMUNE)

# Create maps for a specific date (auto-download)
files <- prepare_comuni_maps(pfun = 61, date = "2020-01-01")

# No simplification (larger files, more detail)
files <- prepare_comuni_maps(simplify = FALSE)

# Keep all attributes from SITUAS
files <- prepare_comuni_maps(keep_attributes = NULL)

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