---
title: "API y datos"
description: "Documentación de festivos.io: el dataset estático (JSON e ICS bajo /v1), la API de consulta en el edge (is-holiday, municipio, puentes, días hábiles), suscripción a calendario y servidor MCP. Gratis, sin clave."
source: "https://festivos.io/api"
---

# API y datos

Dos formas gratuitas de consumir festivos.io: el **dataset estático** (ficheros JSON e ICS sobre CDN) y una **API de consulta** en el edge para preguntas puntuales. Todos los endpoints son gratuitos y no usan clave. Cada registro festivo conserva una **referencia oficial** y, cuando está disponible, un enlace al documento.

- **Municipios:** 8.132
- **Años de calendario:** 2024, 2025, 2026
- **Formatos:** JSON · iCalendar (.ics)
- **Autenticación:** ninguna — sin clave ni registro
- **CORS:** abierto (API de consulta) · GET y POST para batch
- **Licencia:** CC BY 4.0

## Capa 1 — dataset estático (CDN)

Ficheros planos específicos por año bajo `/v1/` en `https://festivos.io`. Sus URLs permanecen estables, pero el contenido puede corregirse cuando cambia una fuente oficial. Son cacheables e idóneos para builds y descargas masivas.

| Endpoint | Descripción |
| --- | --- |
| `GET /v1/{year}/municipio/{ine}.json` | registros publicados de un municipio; cobertura local variable |
| `GET /v1/{year}/municipio/{ine}.ics` | el mismo, en iCalendar |
| `GET /v1/{year}/ccaa/{ISO}.json` | nacional + autonómico de una comunidad |
| `GET /v1/{year}/reverse/{MM-DD}.json` | qué municipios celebran ese día |
| `GET /v1/{year}/coverage.json` | métricas de cobertura |
| `GET /v1/{year}/analitica/resumen.json` | score, distribuciones y medias ponderadas |
| `GET /v1/{year}/analitica/ranking.json` | ranking municipal y elegibilidad |
| `GET /v1/{year}/analitica/dias.json` | impacto de los 365/366 días |
| `GET /v1/{year}/analitica/dias/{MM-DD}.json` | impacto diario por habitantes y territorio |
| `GET /v1/analitica/panel.json` | comparación anual con cohorte y pesos fijos |
| `GET /v1/2026/fiscal.json` | calendario del contribuyente 2026 (AEAT) |
| `GET /v1/2026/fiscal/autonomo.json` | calendario fiscal del autónomo 2026 (AEAT) |
| `GET /v1/2026/escolar.json` | calendario escolar 2026–2027 (17 CCAA + Ceuta y Melilla) |
| `GET /v1/2026/escolar/{ISO}.json` | calendario escolar 2026–2027 de un territorio |
| `GET /v1/ref/municipios.json` | diccionario INE |
| `GET /v1/ref/poblacion/{year}.json` | Padrón municipal 2024–2025: total y sexo |
| `GET /v1/ref/poblacion/index.json` | revisiones municipales disponibles |
| `GET /v1/ref/poblacion.json` | alias de la última revisión municipal completa |
| `GET /v1/ref/demografia/{year}.json` | Censo Anual 2021–2025: perfil demográfico municipal |
| `GET /v1/ref/demografia/index.json` | años de Censo disponibles |
| `GET /v1/ref/demografia.json` | alias del último Censo municipal disponible |
| `GET /v1/ref/poblacion-ecp/{date}.json` | ECP provisional; cobertura no municipal completa |
| `GET /v1/ref/poblacion-ecp/index.json` | fechas ECP disponibles |
| `GET /v1/ref/poblacion-ecp.json` | alias de la última ECP provisional |
| `GET /v1/schema/{contract}.json` | esquemas JSON públicos |
| `GET /v1/ref/search.json` | índice de búsqueda |

Códigos: municipio = **INE de 5 dígitos** (Madrid = `28079`); comunidad = **ISO 3166-2** (Cataluña = `ES-CT`); provincia = **CPRO de 2 dígitos** (`28`). Años disponibles: `2024`, `2025`, `2026`.

```sh
# El calendario publicado de un municipio (estático, sobre CDN)
curl "https://festivos.io/v1/2026/municipio/43148.json"
# Lo mismo en iCalendar, para suscribir en tu calendario
curl "https://festivos.io/v1/2026/municipio/43148.ics"
```

## Capa 2 — API de consulta (edge)

Para preguntas concretas sin descargar el calendario entero. Base: `https://api.festivos.io`.

| Endpoint | Descripción |
| --- | --- |
| `GET /v1/is-holiday?date=YYYY-MM-DD&municipio=INE5` | ¿es festivo? un municipio, una fecha |
| `GET /v1/municipio/:ine?year=YYYY&from=&to=&level=` | festivos de un municipio (rango/nivel opcional) |
| `GET /v1/puentes?municipio=INE5&year=YYYY` | puentes de un municipio |
| `GET /v1/dias-habiles?municipio=INE5&from=YYYY-MM-DD&to=YYYY-MM-DD` | días hábiles entre dos fechas |
| `GET /v1/dias-habiles/sumar?municipio=INE5&date=YYYY-MM-DD&n=INT` | suma o resta días hábiles |
| `GET /v1/dias-habiles/siguiente?municipio=INE5&date=YYYY-MM-DD` | siguiente día hábil |
| `GET /v1/dias-habiles/anterior?municipio=INE5&date=YYYY-MM-DD` | anterior día hábil |
| `GET /v1/dias-habiles/ultimo-mes?municipio=INE5&year=YYYY&month=1-12` | último día hábil del mes |
| `POST /v1/batch` | lote de consultas is-holiday |

```sh
# ¿El 19 de agosto de 2026 es festivo en Tarragona (INE 43148)?
curl "https://api.festivos.io/v1/is-holiday?date=2026-08-19&municipio=43148"
# → { "holiday": true, "festivos": [{ "name": { "ca": "Sant Magí", "es": "Sant Magí" }, "level": "local", … }] }
```

## Acceso y límites

- El dataset estático y todos los endpoints de consulta —incluidas las operaciones avanzadas de días hábiles y `batch`— son gratuitos y no requieren clave.
- La API de consulta conserva un límite razonable por IP únicamente para prevenir abuso; no separa planes ni desbloquea funciones. El dato sigue bajo CC BY 4.0.
- `batch` acepta de 1 a 100 consultas en un máximo de 64 KiB; cada elemento consume una unidad del límite.

## Caché

- `/v1/*`: ficheros estáticos sobre CDN, cacheables.
- Páginas Markdown (`.md` / `Accept: text/markdown`): `Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400`, `X-Robots-Tag: noindex`.

## Calendario (ICS)

Cada municipio expone un `.ics` específico por año. Su URL permanece estable y puede reflejar correcciones de ese año; para el siguiente se usa una URL nueva:

```
https://festivos.io/v1/2026/municipio/43148.ics
```

## Servidor MCP (agentes e IA)

```sh
claude mcp add --transport sse festivos https://mcp.festivos.io/sse
```

## Idiomas y Markdown

Español y, en su territorio, la lengua cooficial (ca, gl, eu, ca-valencia), además de inglés — cada versión con su URL y `hreflang`. Cada página de datos tiene además versión **Markdown**: añade `.md` a la ruta, o envía `Accept: text/markdown` (páginas SSR).

## Cobertura y fuentes

- Cobertura por comunidad: https://festivos.io/cobertura (Markdown: https://festivos.io/cobertura.md)
- Analítica comparable: https://festivos.io/observatorio
- Fuentes: BOE, boletines autonómicos, INE, AEAT y consejerías de educación. Padrón, Censo Anual y ECP son operaciones estadísticas distintas del INE y sus denominadores no se mezclan.
- El impacto diario local o mixto agrega exactamente los registros publicados, pero puede ser un límite inferior donde la capa local esté incompleta.
- Los JSON municipales incluyen `license` y `attribution`; cada registro festivo conserva `source.ref` y, cuando existe, `source.url`. Los índices y ficheros de referencia documentan su origen y esquema por separado.
- No sustituye al boletín oficial: verifica la referencia o el enlace disponible para decisiones legales, laborales o fiscales. Servicio «tal cual», sin garantía.

---

Datos: festivos.io — CC BY 4.0. Fuente oficial: Agencia Estatal BOE y boletines autonómicos (Ley 37/2007).