---
title: "API and data"
description: "festivos.io documentation: the static dataset (JSON and ICS under /v1), the edge query API (is-holiday, municipio, puentes, working days), calendar subscription and MCP server. Free, no key."
source: "https://festivos.io/en/api"
---

# API and data

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. Every endpoint is free and keyless. Every holiday record keeps an **official source reference** and, when available, a document link.

- **Municipalities:** 8,132
- **Calendar years:** 2024, 2025, 2026
- **Formats:** JSON · iCalendar (.ics)
- **Auth:** none — no key or sign-up
- **CORS:** open (query API) · GET, plus POST for batch
- **License:** CC BY 4.0

## Layer 1 — static dataset (CDN)

Year-specific flat files under `/v1/` on `https://festivos.io`. Their URLs remain stable, while the content may be corrected when an official source changes. They are cacheable and suitable for builds and bulk downloads.

| Endpoint | Description |
| --- | --- |
| `GET /v1/{year}/municipio/{ine}.json` | published records for one municipality; local coverage varies |
| `GET /v1/{year}/municipio/{ine}.ics` | the same, in iCalendar |
| `GET /v1/{year}/ccaa/{ISO}.json` | national + regional for a region |
| `GET /v1/{year}/reverse/{MM-DD}.json` | which municipalities celebrate that day |
| `GET /v1/{year}/coverage.json` | coverage metrics |
| `GET /v1/{year}/analitica/resumen.json` | score, distributions and population-weighted means |
| `GET /v1/{year}/analitica/ranking.json` | municipal ranking and eligibility |
| `GET /v1/{year}/analitica/dias.json` | impact for all 365/366 days |
| `GET /v1/{year}/analitica/dias/{MM-DD}.json` | daily impact by residents and territory |
| `GET /v1/analitica/panel.json` | year comparison with a fixed cohort and weights |
| `GET /v1/2026/fiscal.json` | 2026 taxpayer calendar (AEAT) |
| `GET /v1/2026/fiscal/autonomo.json` | 2026 self-employed tax calendar (AEAT) |
| `GET /v1/2026/escolar.json` | 2026–2027 school calendar (17 autonomous communities + Ceuta and Melilla) |
| `GET /v1/2026/escolar/{ISO}.json` | 2026–2027 school calendar for one territory |
| `GET /v1/ref/municipios.json` | INE dictionary |
| `GET /v1/ref/poblacion/{year}.json` | 2024–2025 Municipal Register: total and sex |
| `GET /v1/ref/poblacion/index.json` | available municipal revisions |
| `GET /v1/ref/poblacion.json` | alias for the latest complete municipal revision |
| `GET /v1/ref/demografia/{year}.json` | 2021–2025 Annual Census: municipal demographic profile |
| `GET /v1/ref/demografia/index.json` | available Census years |
| `GET /v1/ref/demografia.json` | alias for the latest available municipal Census |
| `GET /v1/ref/poblacion-ecp/{date}.json` | provisional ECP; not full municipal coverage |
| `GET /v1/ref/poblacion-ecp/index.json` | available ECP dates |
| `GET /v1/ref/poblacion-ecp.json` | alias for the latest provisional ECP |
| `GET /v1/schema/{contract}.json` | public JSON Schemas |
| `GET /v1/ref/search.json` | search index |

Codes: municipality = **5-digit INE** (Madrid = `28079`); region = **ISO 3166-2** (Catalonia = `ES-CT`); province = **2-digit CPRO** (`28`). Available years: `2024`, `2025`, `2026`.

```sh
# 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"
```

## Layer 2 — edge query API

For specific questions without downloading the whole calendar. Base: `https://api.festivos.io`.

| Endpoint | Description |
| --- | --- |
| `GET /v1/is-holiday?date=YYYY-MM-DD&municipio=INE5` | is it a holiday? one municipality, one date |
| `GET /v1/municipio/:ine?year=YYYY&from=&to=&level=` | a municipality's holidays (optional range/level) |
| `GET /v1/puentes?municipio=INE5&year=YYYY` | long weekends for a municipality |
| `GET /v1/dias-habiles?municipio=INE5&from=YYYY-MM-DD&to=YYYY-MM-DD` | working days between two dates |
| `GET /v1/dias-habiles/sumar?municipio=INE5&date=YYYY-MM-DD&n=INT` | add or subtract working days |
| `GET /v1/dias-habiles/siguiente?municipio=INE5&date=YYYY-MM-DD` | next working day |
| `GET /v1/dias-habiles/anterior?municipio=INE5&date=YYYY-MM-DD` | previous working day |
| `GET /v1/dias-habiles/ultimo-mes?municipio=INE5&year=YYYY&month=1-12` | last working day of the month |
| `POST /v1/batch` | batch of is-holiday queries |

```sh
# 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", … }] }
```

## Access & limits

- The static dataset and every query endpoint —including advanced working-day operations and `batch`— are free and require no key.
- The query API keeps a reasonable per-IP limit solely to prevent abuse; it does not separate plans or unlock features. The data remains CC BY 4.0.
- `batch` accepts 1–100 queries in at most 64 KiB; every item consumes one rate-limit unit.

## Caching

- `/v1/*`: static files over CDN, cacheable.
- Markdown pages (`.md` / `Accept: text/markdown`): `Cache-Control: public, s-maxage=3600, stale-while-revalidate=86400`, `X-Robots-Tag: noindex`.

## Calendar (ICS)

Each municipality exposes a year-specific `.ics` feed. Its URL remains stable and may reflect corrections to that year; use a new URL for the next year:

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

## MCP server (agents & AI)

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

## Languages & Markdown

Spanish and, in its territory, the co-official language (ca, gl, eu, ca-valencia), plus English — each version with its URL and `hreflang`. Every data page also has a **Markdown** version: append `.md` to the path, or send `Accept: text/markdown` (SSR pages).

## Coverage & sources

- Coverage by region: https://festivos.io/en/coverage (Markdown: https://festivos.io/en/coverage.md)
- Comparable analytics: https://festivos.io/en/observatory
- Sources: BOE, regional gazettes, INE, AEAT and education departments. The INE Municipal Register, Annual Population Census and ECP are separate statistical operations and their denominators are never mixed.
- Daily local or mixed impact is an exact aggregation of published records, but may be a lower bound where the local-holiday layer is incomplete.
- Municipality JSON files include `license` and `attribution`; every holiday record keeps `source.ref` and, when present, `source.url`. Index and reference files document their origin and schema separately.
- Not an official source: verify the available reference or link before legal, employment or tax decisions. Service provided "as is", without warranty.

---

Data: festivos.io — CC BY 4.0. Official source: State Official Gazette (BOE) and regional gazettes (Law 37/2007).