{"id":17541,"library":"comuni-json","title":"Italian Municipalities JSON Database","description":"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).","status":"active","version":"1.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/matteocontrini/comuni-json","tags":["javascript"],"install":[{"cmd":"npm install comuni-json","lang":"bash","label":"npm"},{"cmd":"yarn add comuni-json","lang":"bash","label":"yarn"},{"cmd":"pnpm add comuni-json","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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');`","wrong":"import { comuniData } from 'comuni-json';","symbol":"comuniData","correct":"import comuniData from 'comuni-json/comuni.json';"},{"note":"When using CommonJS, explicitly reference the `comuni.json` file. The package's `main` entry point may not directly resolve to the data file.","wrong":"const allComuni = require('comuni-json');","symbol":"allComuni","correct":"const allComuni = require('comuni-json/comuni.json');"}],"quickstart":{"code":"import comuniData from 'comuni-json/comuni.json';\n\nconsole.log(`Loaded ${comuniData.length} Italian municipalities.`);\n\n// Find a specific municipality by name (case-insensitive)\nconst findComuneByName = (name) => {\n  return comuniData.find(\n    (comune) => comune.nome.toLowerCase() === name.toLowerCase()\n  );\n};\n\nconst roma = findComuneByName('Roma');\nif (roma) {\n  console.log(`\\nFound Roma:`);\n  console.log(`  ISTAT Code: ${roma.codice}`);\n  console.log(`  Region: ${roma.regione.nome}`);\n  console.log(`  CAPs: ${roma.cap.join(', ')}`);\n  console.log(`  Population (2011): ${roma.popolazione}`);\n} else {\n  console.log('\\nRoma not found.');\n}\n\n// Filter municipalities by region code (e.g., Lazio, code '12')\nconst lazioComuni = comuniData.filter(\n  (comune) => comune.regione.codice === '12'\n);\nconsole.log(`\\nThere are ${lazioComuni.length} municipalities in Lazio.`);\n\n// Example of accessing a potentially empty field (codiceCatastale)\nconst comuneWithEmptyCodice = comuniData.find(\n  (comune) => comune.codiceCatastale === ''\n);\nif (comuneWithEmptyCodice) {\n  console.log(\n    `\\nExample of comune with empty codiceCatastale: ${comuneWithEmptyCodice.nome}`\n  );\n} else {\n  console.log('\\nNo comune found with empty codiceCatastale in this dataset.');\n}","lang":"javascript","description":"Loads the complete list of Italian municipalities and demonstrates basic data access, searching by name, and filtering by region code, highlighting common data structures."},"warnings":[{"fix":"For professional use, consider official, paid services from Poste Italiane.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your code to no longer reference the `cm` field. Consider using the `provincia` field for regional subdivisions.","message":"The `cm` field (for Metropolitan City) was removed from the dataset. Code relying on this field will break.","severity":"breaking","affected_versions":">=2019-02-15 release"},{"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.","message":"German or other non-Italian denominations were removed from the `nome` field to ensure consistency with Italian names.","severity":"breaking","affected_versions":">=2019-02-20 release"},{"fix":"Cross-reference with official Poste Italiane announcements for the latest CAPs for recently formed communes if absolute accuracy is critical.","message":"CAPs for newly established municipalities are often provisional and subject to change by Poste Italiane without immediate update in this dataset.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Implement checks for empty strings when accessing `codiceCatastale` to prevent unexpected behavior in your application.","message":"The `codiceCatastale` field can be an empty string if the cadastral code has not yet been defined by the Agenzia delle Entrate.","severity":"gotcha","affected_versions":">=2019-02-15 release"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Ensure `comuni-json` is installed (`npm install comuni-json`) and the import path is exactly `comuni-json/comuni.json`.","cause":"The module path is incorrect, or the package is not installed.","error":"Error: Cannot find module 'comuni-json/comuni.json'"},{"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); }`","cause":"Attempting to access properties of a municipality object that was not found (e.g., after a filter or find operation returning `undefined`).","error":"TypeError: Cannot read properties of undefined (reading 'cap')"},{"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.","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.","error":"Property 'popolazione' does not exist on type '{ ... }'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}