Italian Municipalities JSON Database

1.0.0 verified Thu Apr 23 auth: no javascript

The `comuni-json` package provides an unofficial database of Italian municipalities in a static JSON format, integrating data from official ISTAT (National Institute of Statistics) and ANCI (National Association of Italian Municipalities) sources. The npm package is currently at version `1.0.0`, with the underlying data last updated to January 1, 2020, encompassing 7904 municipalities. The project maintains an irregular release cadence, typically updating in response to new ISTAT administrative changes or Poste Italiane's CAP (Postcode) revisions. A key characteristic is its open-source nature, offering a readily accessible dataset for development and research. Crucially, the project explicitly states that the completeness and correctness of the CAP data cannot be guaranteed, making it unsuitable for professional applications requiring absolute data reliability, in contrast to commercial, paid services. The dataset structure includes fields such as `nome` (name), `codice` (ISTAT code), `zona` (geographic zone), `regione` (region), `provincia` (province), `sigla` (vehicle registration plate code), `codiceCatastale` (cadastral code), `cap` (an array of postcodes), and `popolazione` (population from the 2011 census).

Common errors

error Error: Cannot find module 'comuni-json/comuni.json' ↓

cause The module path is incorrect, or the package is not installed.

fix

Ensure comuni-json is installed (npm install comuni-json) and the import path is exactly comuni-json/comuni.json.

error TypeError: Cannot read properties of undefined (reading 'cap') ↓

cause Attempting to access properties of a municipality object that was not found (e.g., after a filter or find operation returning `undefined`).

fix

Always check if the result of a search or filter operation is not undefined before attempting to access its properties. For example: const comune = findComune(name); if (comune) { console.log(comune.cap); }

error Property 'popolazione' does not exist on type '{ ... }' ↓

cause TypeScript error due to an outdated type definition or trying to access the `popolazione` field in an older version of the data where it wasn't present, or assuming a string type.

fix

Ensure your type definitions are up-to-date. The popolazione field was added in the 2018-10-26 update and is a numeric type. Validate its presence and type if working with potentially older data or strict type checks.

Warnings

gotcha The completeness and correctness of the CAP (Postcode) data cannot be guaranteed as Poste Italiane does not publicly release a full list. This data is explicitly noted as unsuitable for professional use or applications requiring high reliability. ↓

fix For professional use, consider official, paid services from Poste Italiane.

breaking The `cm` field (for Metropolitan City) was removed from the dataset. Code relying on this field will break. ↓

fix Update your code to no longer reference the `cm` field. Consider using the `provincia` field for regional subdivisions.

breaking German or other non-Italian denominations were removed from the `nome` field to ensure consistency with Italian names. ↓

fix If your application relied on alternative language names within the `nome` field, you will need to adjust your logic or integrate external translation sources.

gotcha CAPs for newly established municipalities are often provisional and subject to change by Poste Italiane without immediate update in this dataset. ↓

fix Cross-reference with official Poste Italiane announcements for the latest CAPs for recently formed communes if absolute accuracy is critical.

gotcha The `codiceCatastale` field can be an empty string if the cadastral code has not yet been defined by the Agenzia delle Entrate. ↓

fix Implement checks for empty strings when accessing `codiceCatastale` to prevent unexpected behavior in your application.

Install

npm install comuni-json

yarn add comuni-json

pnpm add comuni-json

Imports

comuniData
wrong
```
import { comuniData } from 'comuni-json';
```
correct
```
import comuniData from 'comuni-json/comuni.json';
```
This package exports a single JSON array directly. You must import the `.json` file explicitly. For CommonJS, use `const comuniData = require('comuni-json/comuni.json');`
allComuni
wrong
```
const allComuni = require('comuni-json');
```
correct
```
const allComuni = require('comuni-json/comuni.json');
```
When using CommonJS, explicitly reference the `comuni.json` file. The package's `main` entry point may not directly resolve to the data file.

Quickstart

Loads the complete list of Italian municipalities and demonstrates basic data access, searching by name, and filtering by region code, highlighting common data structures.

import comuniData from 'comuni-json/comuni.json';

console.log(`Loaded ${comuniData.length} Italian municipalities.`);

// Find a specific municipality by name (case-insensitive)
const findComuneByName = (name) => {
  return comuniData.find(
    (comune) => comune.nome.toLowerCase() === name.toLowerCase()
  );
};

const roma = findComuneByName('Roma');
if (roma) {
  console.log(`\nFound Roma:`);
  console.log(`  ISTAT Code: ${roma.codice}`);
  console.log(`  Region: ${roma.regione.nome}`);
  console.log(`  CAPs: ${roma.cap.join(', ')}`);
  console.log(`  Population (2011): ${roma.popolazione}`);
} else {
  console.log('\nRoma not found.');
}

// Filter municipalities by region code (e.g., Lazio, code '12')
const lazioComuni = comuniData.filter(
  (comune) => comune.regione.codice === '12'
);
console.log(`\nThere are ${lazioComuni.length} municipalities in Lazio.`);

// Example of accessing a potentially empty field (codiceCatastale)
const comuneWithEmptyCodice = comuniData.find(
  (comune) => comune.codiceCatastale === ''
);
if (comuneWithEmptyCodice) {
  console.log(
    `\nExample of comune with empty codiceCatastale: ${comuneWithEmptyCodice.nome}`
  );
} else {
  console.log('\nNo comune found with empty codiceCatastale in this dataset.');
}