API festività italiane

Un endpoint per sapere se un giorno è lavorativo in un comune italiano, tenendo conto delle festività nazionali e della festa del patrono. Copre tutti i 7.904 comuni ISTAT, di cui 5.617 con la data presa dalla scheda del comune, non dedotta.

Perché serve

Il calendario liturgico dice quando si celebra un santo, non quando chiude un comune. San Paolo è il 29 giugno, ma ad Aversa la festa patronale è il 25 gennaio. Le date qui dentro sono quelle civiche, prese comune per comune, non dedotte dal santo.

Indirizzo base

https://festivitaitalia.com

Endpoint

GET /v1/comuni?q=berg

Cerca un comune per nome e restituisce il suo codice ISTAT. Da qui parte tutto il resto.

Provalo

GET /v1/festivita?comune=016024&anno=2026

Tutte le festività dell'anno per quel comune, nazionali e patronali, già unite quando cadono lo stesso giorno.

Provalo

Risposta

{
  "comune": {
    "codice": "016024",
    "nome": "Bergamo",
    "sigla": "BG",
    "regione": "Lombardia",
    "slug": "bergamo-bg",
    "patroni": [{ "santo": "sant'Alessandro di Bergamo", "data": "08-26" }]
  },
  "anno": 2026,
  "festivita": [
    { "data": "2026-01-01", "nome": "Capodanno", "tipo": "nazionale" },
    { "data": "2026-04-06", "nome": "Lunedì dell'Angelo", "tipo": "nazionale" },
    { "data": "2026-08-26", "nome": "Patrono: sant'Alessandro di Bergamo", "tipo": "patrono" },
    { "data": "2026-10-04", "nome": "San Francesco d'Assisi", "tipo": "nazionale" }
  ]
}

GET /v1/giorno-lavorativo?comune=016024&data=2026-08-26

Dice se quel giorno si lavora, e se no perché. Risponde { "lavorativo": false, "motivo": "Patrono: sant'Alessandro di Bergamo" }.

Provalo

GET /v1/prossimo-lavorativo?comune=016024&data=2026-12-24

Il primo giorno lavorativo successivo alla data indicata.

Provalo

GET /v1/aggiungi-lavorativi?comune=016024&data=2026-12-24&giorni=3

Aggiunge N giorni lavorativi a una data. È la chiamata che serve agli e-commerce per stimare la consegna.

Provalo

GET /v1/ical/016024.ics

Feed iCal con le festività dell'anno corrente e del successivo, da sottoscrivere in qualsiasi calendario.

Provalo

Parametri comuni

Il parametro comune è sempre il codice ISTAT a sei cifre, che ottieni da /v1/comuni. Le date sono nel formato YYYY-MM-DD. Aggiungi &sabato=true se nella tua attività il sabato è lavorativo.

Errori

In caso di errore la risposta ha codice 400 o 404 e un corpo JSON con una sola chiave errore che spiega cosa manca, in italiano.

Limiti e costi

L'API è gratuita e senza chiave durante la fase di avvio. Le risposte sono in cache per un'ora e CORS è aperto, quindi la puoi chiamare anche dal browser. Per volumi elevati, garanzie di servizio o una copia completa del dataset in CSV con licenza annuale, scrivimi.

Qualità dichiarata

Su un campione di 259 comuni confrontati con una fonte indipendente l'accordo è del 94,2%. I comuni la cui data è dedotta dal calendario invece che presa dalla scheda comunale sono esclusi dalle pagine pubbliche ma restano interrogabili. Se trovi un errore, segnalalo: correggo in giornata.

Da dove vengono i dati

Patroni e date dalle schede comunali di Wikipedia in italiano (CC BY-SA 4.0), collegamenti comune-voce da Wikidata (CC0), elenco dei comuni dai codici ISTAT. Le festività nazionali seguono la legge 260/1949 e successive modifiche, compresa la legge 151/2025 che dal 2026 reintroduce il 4 ottobre. Riusando questi dati va citata la fonte.

Scrivimi

Integrazioni, licenze e segnalazioni: ook71654@gmail.com