# FestivosAPI

> Spain public holidays JSON API -- national + all 19 regions (17 CCAA + Ceuta + Melilla) + municipio-level *fiestas patronales*, for payroll/HR/scheduling software that needs to know: is this a working day in this specific town?

Full machine-readable contract (OpenAPI 3.1, every endpoint/parameter/example): https://festivos.dsl4.com/openapi.json
Human docs: https://festivos.dsl4.com/
Legal notice & privacy policy: https://festivos.dsl4.com/legal
Privacy policy (RGPD, ES): https://festivos.dsl4.com/privacidad
API terms of service (ES): https://festivos.dsl4.com/terminos

## Auth

Every `/v1/*` endpoint except `/v1/ccaa`, `/v1/coverage`, and `POST /v1/signup` requires an API key, either as header `X-API-Key: <key>` or query param `?api_key=<key>`. Get one instantly and free, no email required:

```
curl -s -X POST https://festivos.dsl4.com/v1/signup
```

## Core endpoints

- `GET /v1/holidays?municipio=&year=` -- every holiday for a municipio in a year
- `GET /v1/is-holiday?date=&municipio=` -- is this exact date a holiday for this municipio
- `GET /v1/next?municipio=&from=` -- the next upcoming holiday
- `GET /v1/municipios?q=&ccaa=&province=` -- search the 8,000+ municipio registry for an INE code
- `GET /v1/ccaa` -- list the 19 regions (no key required)
- `GET /v1/coverage` -- the live municipio-level coverage ledger (no key required)
- `POST /v1/signup` -- create a free-tier key (no key required)

`municipio` accepts either a 5-digit INE code (e.g. `28079` = Madrid) or an exact/unambiguous municipio name.

## Rate limits

Daily request cap per key, counted per UTC day: Free 100, Basic 20,000, Pro 200,000. Every authenticated response carries `X-RateLimit-Limit` / `X-RateLimit-Remaining`; over the cap you get `429` with `Retry-After`.

## Data honesty

National + all 19 regional calendars are 100% complete. Municipio-level local data is real and sourced from official open-data portals and gazettes -- see `GET /v1/coverage` for the live, per-region ledger (covered vs. verified-none-declared vs. unaccounted). Only 2026 is loaded as of this file; 2027 data lands once the BOE publishes its resolution, expected autumn 2026.

## Pricing

Free (0 EUR, 100 req/day) -> Basic (9 EUR/mo, 20,000 req/day) -> Pro (19 EUR/mo, 200,000 req/day). Subscribe via the Stripe Payment Links linked from https://festivos.dsl4.com/.