# Italian Municipalities: ISTAT & Cadastral Codes Lookup (`nexus-studio/italia-comuni-istat`) Actor

Official ISTAT list of Italian comuni as clean JSON: ISTAT code, cadastral (Belfiore) code, province, region, NUTS, provincial capital flag. Filter or look up by code. CC BY 4.0.

- **URL**: https://apify.com/nexus-studio/italia-comuni-istat.md
- **Developed by:** [Nexus Studio](https://apify.com/nexus-studio) (community)
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Italian Municipalities: ISTAT & Cadastral Codes Lookup

The official **ISTAT list of Italian comuni** (about 7,900) as clean JSON, ready for joins and lookups: **ISTAT code**, **cadastral (Belfiore) code**, province (name, plate code, type), region, geographic area, **NUTS** codes, provincial-capital flag. Look up specific codes, filter by region or province, or take the whole list. No API key, no proxies.

### What you get

`istatCode`, `istatNumericCode`, `name`, `nameItalian`, `nameOtherLanguage` (e.g. German names in South Tyrol), `cadastralCode`, `provinceAbbreviation`, `provinceName`, `provinceType`, `regionCode`, `regionName`, `geographicArea`, `isProvincialCapital`, `legalPopulation2011`, `nuts1/2/3` (newest edition in the file, reported in `nutsEdition`), plus `sourceFile`, `license`, `attribution`.

### Who is it for

- Developers and data engineers who need to **map Belfiore ↔ ISTAT codes** (e.g. when parsing tax codes, invoices or public datasets).
- Analysts joining Italian datasets by municipality.
- Teams that want an always-current reference table without maintaining a spreadsheet after municipal mergers.

### How to use

- Lookup: `{"cadastralCodes": ["F205", "H501"], "istatCodes": ["015146"]}` — codes not found are listed in the run summary and are **not charged**.
- Filter: `{"region": "Lombardia"}` · `{"province": "MI", "capitalsOnly": true}` · `{"nameContains": "bolzano"}`.
- Everything: leave the input empty and raise `maxItems` (default 1000, max 10,000).

### Pricing (pay per event)

- **Actor start:** $0.005 per run.
- **Comune record:** $0.0005 per record returned ($0.50 per 1,000; the whole list is about $4).

### Data source, licence and attribution

- Source: [Istat, "Codici delle unità amministrative" – Elenco dei comuni italiani](https://www.istat.it/classificazione/codici-dei-comuni-delle-province-e-delle-regioni).
- Licence: [Creative Commons Attribution 4.0 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.it) per the [Istat legal notice](https://www.istat.it/note-legali/): commercial use and modification allowed with attribution.
- **Attribution to use if you republish the data:** "Source: Istat, Elenco dei comuni italiani, CC BY 4.0. Data reformatted." Indicate that changes were made.
- Not affiliated with or endorsed by Istat.

### Limits and notes

- `legalPopulation2011` appears only if the Istat file carries that column: the current file (checked 29/10/2026) no longer does. Use Istat demographic statistics for population.
- Istat reorganises municipalities often (mergers, Sardinia reform from 2026). The Actor reads the file at every run, so it follows the latest published list; if the layout changes, it stops with a clear error.
- Historical codes of suppressed municipalities are not part of this list.

***

## Comuni italiani: codici ISTAT e catastali

L'**elenco ufficiale ISTAT dei comuni italiani** (circa 7.900) in JSON pulito, pronto per join e ricerche: **codice ISTAT**, **codice catastale (Belfiore)**, provincia (nome, sigla, tipo), regione, ripartizione geografica, codici **NUTS**, flag di capoluogo. Cerca per codice, filtra per regione o provincia, oppure prendi l'elenco intero.

### Cosa ottieni

`istatCode`, `istatNumericCode`, `name`, `nameItalian`, `nameOtherLanguage` (ad es. i nomi in tedesco in Alto Adige), `cadastralCode`, `provinceAbbreviation`, `provinceName`, `provinceType`, `regionCode`, `regionName`, `geographicArea`, `isProvincialCapital`, `legalPopulation2011`, `nuts1/2/3` (edizione più recente del file, indicata in `nutsEdition`), più `sourceFile`, `license`, `attribution`.

### A chi serve

- Sviluppatori e data engineer che devono **collegare codice Belfiore e codice ISTAT** (ad es. leggendo codici fiscali, fatture o dataset pubblici).
- Analisti che uniscono dataset italiani per comune.
- Team che vogliono una tabella di riferimento sempre aggiornata, senza rincorrere fusioni e cambi di comune.

### Come si usa

- Ricerca: `{"cadastralCodes": ["F205", "H501"], "istatCodes": ["015146"]}`; i codici non trovati compaiono nel riepilogo e **non vengono addebitati**.
- Filtri: `{"region": "Lombardia"}` · `{"province": "MI", "capitalsOnly": true}` · `{"nameContains": "bolzano"}`.
- Tutto: lascia l'input vuoto e alza `maxItems` (predefinito 1000, massimo 10.000).

### Prezzi (pagamento a evento)

- **Avvio dell'Actor:** 0,005 $ a esecuzione.
- **Record comune:** 0,0005 $ a record (0,50 $ ogni 1.000; l'elenco intero costa circa 4 $).

### Fonte, licenza e citazione

- Fonte: [Istat, «Codici delle unità amministrative» – Elenco dei comuni italiani](https://www.istat.it/classificazione/codici-dei-comuni-delle-province-e-delle-regioni).
- Licenza: [Creative Commons Attribuzione 4.0 (CC BY 4.0)](https://creativecommons.org/licenses/by/4.0/deed.it) secondo le [note legali Istat](https://www.istat.it/note-legali/): uso commerciale e modifica consentiti con attribuzione.
- **Citazione da usare se ripubblichi i dati:** «Fonte: Istat, Elenco dei comuni italiani, CC BY 4.0. Dati rielaborati.» Indica che sono state fatte modifiche.
- Servizio indipendente, non affiliato né approvato dall'Istat.

### Limiti e note

- `legalPopulation2011` compare solo se il file Istat ha quella colonna: il file attuale (verificato il 29/10/2026) non ce l'ha più. Per la popolazione usa le statistiche demografiche Istat.
- L'Istat aggiorna spesso i comuni (fusioni, riforma della Sardegna dal 2026). L'Actor legge il file a ogni esecuzione e segue l'ultimo elenco pubblicato; se il tracciato cambia, si ferma con un errore chiaro.
- I codici storici dei comuni soppressi non fanno parte di questo elenco.

# Actor input Schema

## `istatCodes` (type: `array`):

6-digit ISTAT municipality codes (e.g. 015146 for Milano). Leading zeros optional.

## `cadastralCodes` (type: `array`):

Belfiore codes such as F205 (Milano) or H501 (Roma). Case-insensitive.

## `region` (type: `string`):

Region name (e.g. Lombardia) or 2-digit ISTAT region code. Accents and case are ignored.

## `province` (type: `string`):

Two-letter vehicle-plate code of the province (e.g. MI, RM). Empty = all.

## `nameContains` (type: `string`):

Part of the comune name. Accents and case are ignored.

## `capitalsOnly` (type: `boolean`):

Return only comuni that are capoluogo of a province / metropolitan city.

## `maxItems` (type: `integer`):

Upper bound on records returned (and charged).

## Actor input object example

```json
{
  "capitalsOnly": false,
  "maxItems": 1000
}
```

# Actor output Schema

## `results` (type: `string`):

No description

## `runSummary` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("nexus-studio/italia-comuni-istat").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("nexus-studio/italia-comuni-istat").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call nexus-studio/italia-comuni-istat --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nexus-studio/italia-comuni-istat"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/oObHkQdzO8dG0qPTW/builds/dzdH5TQK41FXj3fsB/openapi.json