# Embedded holiday dataset
`holidays.json.gz` powers timeglyph's `holiday` feature — a whole-world
public-holiday lookup (`timeglyph::holiday::lookup(country, date)`).
## Provenance
- **Source:** [python-holidays](https://github.com/vacanza/holidays), the
canonical rule-based holiday library.
- **License:** MIT (redistribution permitted with attribution — see the
repository `NOTICE`). The file here is a *derived work*: dates and names are
python-holidays' own output.
- **Version used:** `holidays` **0.99** (record the new version here whenever you
regenerate — the rules, and thus a few dates/names, change between releases).
- **Generated by:** [`generate_holidays.py`](generate_holidays.py) —
`pip install holidays && python3 data/generate_holidays.py`.
- **Range:** 1980–2100.
- **Coverage:** 248 countries (ISO-3166 alpha-2), 379,163 holiday-dates.
## Format
Gzip of a compact JSON map, keys sorted for byte-stable regeneration:
```json
{ "US": { "2020-07-04": "Independence Day", … }, "CN": { "2020-01-25": "春节", … }, … }
```
Names are in **each country's default locale** (so CN names are in Chinese),
exactly as python-holidays emits them — not translated to English.
## Caveats (documented, still true)
- **Coverage varies by country.** python-holidays supports a different year range
per locale and silently clips the 1980–2100 request, so some countries carry
fewer years. A `None` from `lookup` means "no holiday in the covered data",
**not** "provably an ordinary day".
- **A hit is *consistent with* a public holiday**, per the reference data — an
annotation, not proof the day was observed at a given place. Lunar/lunisolar
and astronomically-derived holidays are python-holidays' best estimates.
- **Not versioned as ground truth.** Treat it as a helpful annotation layer for
timestamp interpretation, not an authoritative calendar of record.
## `zone_country.json`
Maps each IANA time-zone name to its ISO-3166 alpha-2 country (e.g.
`Asia/Shanghai` → `CN`), so a display zone can pick which country's holidays to
annotate a reading with (`timeglyph::holiday::country_for_zone`).
- **Source:** the IANA time-zone database (public domain) — `zone.tab` for
canonical zones, plus the `backward` file's `Link` lines so legacy aliases
(e.g. `Asia/Chongqing` → `Asia/Shanghai`, `US/Eastern` → `America/New_York`)
resolve to the same country as their canonical. Without the aliases, jiff
still renders the time for them but their holidays would never show.
- **Regenerate:** [`generate_zone_country.py`](generate_zone_country.py) —
`python3 data/generate_zone_country.py` (reads the local `zone.tab`, fetches
`backward`). ~553 zones (~135 aliases), sorted.
- Zones with no single country (`Etc/*`, `UTC`) are absent → no holiday annotation.