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. Ningún endpoint exige registro, pago ni clave. Cada dato conserva una referencia oficialy, cuando está disponible, un enlace al documento.
8.132
2024–26
JSON · ICS
no hace falta
Capa 1 · estático
Ficheros versionados bajo /v1/ en festivos.io. Son archivos planos: cachéables, sin servidor que pueda caerse, ideales para builds y descargas masivas.
# 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"
Años disponibles: 2024, 2025, 2026. El código de municipio es el INE de 5 dígitos (p. ej. Madrid = 28079); el de comunidad es el ISO 3166-2 (p. ej. Cataluña = ES-CT). Padrón, Censo Anual y ECP conservan años y denominadores propios: no son intercambiables. La lectura visual y sus cautelas están en el Observatorio.
Capa 2 · consulta
Para preguntas concretas sin descargar el calendario entero. Respuesta JSON yCORS abierto; usa GET salvo el lote POST /v1/batch. Base: https://api.festivos.io.
# ¿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", … }] }
Toda la API de consulta es de uso gratuito y sin clave: is-holiday, municipio, puentes, todas las operaciones de dias-habiles y batch. El límite por IP solo protege el servicio frente a abuso; no separa planes ni desbloquea funciones. En batch, cada elemento consume una unidad del límite. El dato sigue bajo CC BY 4.0 y admite uso comercial con atribución.
Los cálculos de días hábiles se limitan a los calendarios publicados de 2024-01-01 a 2026-12-31. Un rango invertido o un resultado fuera de esa cobertura devuelve 400en vez de omitir silenciosamente los festivos de un año ausente.
Calendario
Cada municipio expone un .ics específico por año. Pégalo como calendario por suscripción en Google Calendar, Apple Calendar u Outlook. Su URL permanece estable y puede reflejar correcciones de ese año; para el siguiente, usa la URL correspondiente.
https://festivos.io/v1/2026/municipio/43148.icsPara agentes e IA
Un servidor MCP expone los festivos y el Padrón municipal como herramientas: el agente entiende el nombre del municipio y responde en lenguaje natural, sin que conozcas el código INE.
# Claude Code (o cualquier cliente MCP, vía URL remota) claude mcp add --transport sse festivos https://mcp.festivos.io/sse # «¿Trabajo mañana en Sabadell?» · «¿Puentes en Barcelona 2026?»
Antes de integrar
No. El dataset estático y todos los endpoints de la API —incluidas las operaciones avanzadas dedias-habiles y batch— son gratuitos y no requieren clave. La API conserva un límite razonable por IP únicamente para prevenir abuso.
Los datos, bajo CC BY 4.0 — uso libre, también comercial, citando la fuente. 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.
BOE, boletines autonómicos, INE, AEAT y consejerías de educación. El detalle, en Fuentes.
No sustituye al boletín oficial. Verifica siempre la referencia o el enlace disponible antes de decisiones jurídicas, laborales o fiscales. Servicio «tal cual», sin garantía.