comuni-json

library1.0.0jsnpmunverified

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

database data

npm install comuni-json

github ↗package ↗

INSTALL

IMPORT

SIG · COMUNI-JSON

comuni-json

databasejavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

comuniData

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

✗ import { comuniData } from '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

✓ const allComuni = require('comuni-json/comuni.json');

✗ const allComuni = require('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.

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.'); }

Debug

Known issues

gotchaThe 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.

affects: >=1.0.0

breakingThe `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.

affects: >=2019-02-15 release

breakingGerman 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.

affects: >=2019-02-20 release

gotchaCAPs 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.

affects: >=1.0.0

gotchaThe `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.

affects: >=2019-02-15 release

Errors

Common errors & fixes

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

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`.

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

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); }`

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

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.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

26 hits · last 30 days

node

Anthropic

OpenAI (training)

Resources

githubhttps://github.com/matteocontrini/comuni-json ↗

packagehttps://www.npmjs.com/package/comuni-json ↗