Holiday history & changelog

Holiday data changes: governments move holidays, add new ones, or withdraw them, and our sources follow. Festivo records every change to a holiday as a revision, so you can see what changed and when.

History began on 4 October 2026. Every holiday that existed then has a revision 0 recording its state at that moment; every change since is a new revision. Changes before that date aren't recorded.

dataVersion is unaffected by these changes: it's a contract version, and holiday data keeps updating within it.

Requests on a plan without the feature return 402 payment_required.

Changelog

Endpoint: GET /v3/public-holidays/changes

Changes to holidays, newest first.

1curl "https://api.getfestivo.com/v3/public-holidays/changes?api_key=YOUR_API_KEY&country=ES"

kind is created, updated, deprecated (withdrawn, see soft-removed holidays) or restored. fields holds each changed field's old and new value, using the same field names as list items; a renamed holiday shows as name. changedAt is when the change reached Festivo.

Single holiday with its history

Endpoint: GET /v3/public-holidays/occurrences/{id} · Pro, Titan

The holiday (id from any list or check item), in the same shape as a list item, plus every revision from revision 0. Withdrawn holidays keep their page, with deprecated: true. Parameters: dataVersion, language.

1{
2  "status": 200,
3  "dataVersion": "3.1.0",
4  "occurrence": {
5    "id": "20260502_3f6c0d2a9b1e47c58d0e6a71b2c4f9e3",
6    "name": "Madrid Community Day",
7    "date": "2026-05-02",
8    "observed": "2026-05-04",
9    "...": "..."
10  },
11  "variant": "madrid-community-day",
12  "revisions": [
13    {
14      "revision": 0,
15      "kind": "baseline",
16      "fields": {
17        "observed": {
18          "old": null,
19          "new": "2026-05-02"
20        },
21        "...": "..."
22      },
23      "changedAt": "2026-10-04T19:20:00Z"
24    },
25    {
26      "revision": 1,
27      "kind": "updated",
28      "fields": {
29        "observed": {
30          "old": "2026-05-02",
31          "new": "2026-05-04"
32        }
33      },
34      "changedAt": "2026-10-12T17:01:12Z"
35    }
36  ]
37}

Single holiday variant

Endpoint: GET /v3/public-holidays/variants/{slug} · Pro, Titan

A variant is one holiday across countries and years (e.g. labour-day). Returns its names and every date it falls on, as list items. Parameters: dataVersion, country, year, includeDeprecated, language.

History fields on list and check (contract 3.1.2)

Request dataVersion=3.1.2 (opt-in, every plan) and each list/check item also carries:

• variant: the holiday's variant slug, for /variants/{slug};
• revision: its latest revision number (0 = unchanged since history began);
• updatedAt: when that revision was recorded, present once the holiday has changed since history began.