Two free ways to consume festivos.io: the static dataset (JSON and ICS files over a CDN) and a query API at the edge for one-off questions. No endpoint requires sign-up, payment or an API key. Every record keeps an official reference and, when available, a document link.
8,132
2024–26
JSON · ICS
not needed
Layer 1 · static
Versioned files under /v1/ on festivos.io. Flat files: cacheable, with no server to go down, ideal for builds and bulk downloads.
# A municipality's published calendar (static, over CDN) curl "https://festivos.io/v1/2026/municipio/43148.json" # The same in iCalendar, to subscribe in your calendar curl "https://festivos.io/v1/2026/municipio/43148.ics"
Available years: 2024, 2025, 2026. The municipality code is the 5-digit INE code (e.g. Madrid = 28079); the region code is ISO 3166-2 (e.g. Catalonia = ES-CT). The Municipal Register, Annual Census and ECP retain their own years and denominators: they are not interchangeable. See the Observatory for the visual interpretation and caveats.
Layer 2 · query
For specific questions without downloading the whole calendar. JSON responses and openCORS; it uses GET except for POST /v1/batch. Base: https://api.festivos.io.
# Is 19 August 2026 a public holiday in 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", … }] }
The whole query API is free and keyless: is-holiday, municipio, puentes, every dias-habiles operation and batch. The per-IP limit only protects the service from abuse; it does not separate plans or unlock features. Eachbatch item consumes one limit unit. The data remains CC BY 4.0 and may be used commercially with attribution.
Working-day calculations are limited to the published calendars from 2024-01-01 to 2026-12-31. A reversed range or a result outside that coverage returns 400instead of silently treating a missing year as holiday-free.
Calendar
Each municipality exposes a year-specific .ics feed. Add it as a subscribed calendar in Google Calendar, Apple Calendar or Outlook. Its URL remains stable and may reflect corrections to that year; use the corresponding URL for the next year.
https://festivos.io/v1/2026/municipio/43148.icsFor agents and AI
An MCP server exposes holidays and the municipal register as tools: the agent understands the municipality name and answers in natural language, without you knowing the INE code.
# Claude Code (or any MCP client, via remote URL) claude mcp add --transport sse festivos https://mcp.festivos.io/sse # "Do I work tomorrow in Sabadell?" · "Long weekends in Barcelona 2026?"
Before integrating
No. The static dataset and every API endpoint —including advanced dias-habilesoperations and batch— are free and require no key. The API keeps a reasonable per-IP limit solely to prevent abuse.
The data, under CC BY 4.0 — free to use, including commercially, with attribution. Municipality JSON files include license andattribution; every holiday record keeps source.ref and, when present,source.url. Index and reference files document their origin and schema separately.
BOE, regional gazettes, INE, AEAT and education departments. The detail is in Sources.
It does not replace the official gazette. Always verify the available reference or link before legal, employment or tax decisions. Service provided "as is", without warranty.