DEV Community: Alexander Denisov

Building hldays #3: A source on every record

Alexander Denisov — Thu, 29 Oct 2026 19:00:00 +0000

In the first post I promised "a source on every record". This post is about what that means in practice: where the data comes from, what "verified" means, and how I keep it from going stale.

The short version: every holiday in hldays carries a link, a verbatim quote and the date it was checked, and the build refuses to call a record verified without them.

What a record looks like

Here is Alenquer's municipal holiday, straight from data/PT/municipalities.yaml:

- id: feriado-municipal
  name: { pt: "Feriado Municipal" }
  type: local
  rule: { easter: 39 }
  status: verified
  source:
    url: "https://irn.justica.gov.pt/Contactos-do-Registo/Espaco-Registos-de-Alenquer"
    verified_at: "2026-10-16"
    quote: "Encerrado no feriado municipal (quinta-feira da Ascensão)"

And a regional one, Madeira's Autonomy Day, which cites the regional decree itself:

- id: dia-da-autonomia
  name: { pt: Dia da Autonomia, en: Autonomy Day }
  type: public
  rule: { fixed: "04-02" }
  valid_from: 2025
  status: verified
  source:
    url: "https://joram.madeira.gov.pt/joram/1serie/Ano%20de%202024/ISerie-206-2024-12-16sup.pdf"
    ref: "Decreto Legislativo Regional n.º 17/2024/M"
    verified_at: "2026-10-16"
    quote: "O dia 2 de abril constitui o feriado do Dia da Autonomia na Região Autónoma da Madeira."

A source has four optional parts:

url: the page or document
ref: a human reference, like a law number
quote: the sentence on that page that states the holiday, copied verbatim
verified_at: when someone (or something) last confirmed it

The quote matters most. A URL alone tells you where to look. The quote tells you what the page said, so you can check it yourself without trusting me.

All of this goes out in the API response. Every holiday in /v1/holidays has its status and source next to the date, unless you ask for include_sources=false:

curl "https://api.hldays.dev/v1/holidays?jurisdiction=PT-30&year=2026"


{
  "date": "2026-04-02",
  "holiday_id": "dia-da-autonomia",
  "type": "public",
  "status": "verified",
  "source": {
    "url": "https://joram.madeira.gov.pt/joram/1serie/...",
    "ref": "Decreto Legislativo Regional n.º 17/2024/M",
    "verified_at": "2026-10-16",
    "quote": "O dia 2 de abril constitui o feriado do Dia da Autonomia na Região Autónoma da Madeira."
  },
  "jurisdiction": { "id": "PT-30", "name": "Região Autónoma da Madeira", "level": "subdivision" }
}

The build enforces it

There are only two statuses: verified and unverified. The rule for verified lives in src/core/validate.ts, which runs on every build:

if (h.status === "verified" && !(h.source?.url && h.source?.verified_at))
  errors.push(`${hw}: verified holidays need source.url and source.verified_at`);

If any record breaks it, npm run build:data fails, so the tests fail, so nothing deploys. It's a small check, but it means "verified" can't drift into meaning "I'm fairly sure".

What counts as an official source is a convention, written in the README: a law, the Diário da República, a municipality's own website, a government registry page. News articles, bank holiday lists and Wikipedia can be useful leads, but a record that only has those stays unverified.

Collecting Portugal: there is no official list

Portugal has 308 municipalities, and each one sets its own holiday. There is no single official list of them. So the data had to be collected one municipality at a time, in a few passes:

A pilot of 22 municipalities , researched carefully to learn which sources are reliable.
A scan of registry pages. This turned out to be the best trick of the whole project.
Research agents for the rest, with strict instructions.
A merge script (research/pt/scripts/merge.py) that combines all of it into the YAML.

The registry trick

Portugal's civil registry offices (IRN) close on the local municipal holiday. Their contact pages say so, in a very regular format: "Encerrado no feriado municipal (...)", "closed on the municipal holiday", with the date or rule in brackets.

Those pages live on an official government domain, and their URLs follow a handful of patterns. So research/pt/scripts/irn_scan.py tries each municipality's name against those patterns and pulls out the bracket:

PATTERNS = ["Registo-Civil-de-{}", "Espaco-Registos-de-{}", "Registo-Civil-Predial-e-Comercial-de-{}",
            "Registo-Civil-e-Predial-de-{}", "Registo-Predial-de-{}", "Registo-Predial-e-Comercial-de-{}"]
RE = re.compile(r"Encerrad[oa] no feriado municipal\s*\(([^)]{3,80})\)", re.I)

That found 102 of the 308 municipalities with no search at all. The merge script then turns the bracket into a rule. Fixed dates ("20 de agosto") are a regex; movable ones are a lookup table of every phrase the scan found:

"quinta-feira da ascensão": ({"easter": 39}, None),
"terceira segunda-feira de julho": ({"nth_weekday": {"month": 7, "weekday": 1, "n": 3}}, None),
"segunda-feira após o primeiro domingo de outubro": ({"nth_weekday": {"month": 10, "weekday": 7, "n": 1, "offset": 1}}, None),

Some phrases needed a judgement call, and those carry a note. Mafra's registry says "5ª quinta-feira da Ascensão", which I read as Ascension Thursday ("5ª" is short for quinta-feira, Thursday). Idanha-a-Nova's says "the third Tuesday after Easter Sunday", which is Easter + 16, even though other lists give a Monday. I kept the official text.

Agents for the rest

For the remaining municipalities I used research agents: LLM agents with web access, each given a batch of about ten municipalities and the same instruction file (research/pt/agent-instructions.md). The rules that mattered most:

Never guess, never fill a field from memory.
"Official" means an official domain that explicitly says it is the feriado municipal.
The quote must come from a page the agent actually fetched. If it only saw a search snippet, it has to say so, and the record becomes secondary.
Report conflicts between sources instead of picking one silently.

Each batch got a hint from a compiled list, labelled as unreliable, so the agent knew what to look for but not what to conclude. The merge script then decides the status, not the agent:

official = a.get("source_tier") == "official" and not a.get("quote_from_snippet")
...
src = {"url": a.get("source_url")}
if official: src["verified_at"] = V
else: src["ref"] = "secondary"

So an agent can't promote its own finding: without an official page and a fetched quote, the record lands as unverified with ref: secondary, and the build check above makes sure it stays that way. The merge also runs in a fixed order (pilot, then IRN, then agents), and an IRN hit that disagrees with a verified pilot record is logged as a mismatch rather than overwriting it.

The agents were useful. They found pages I wouldn't have had the patience to dig up one municipality at a time. Still, I trust the rules in the merge script more than the agents, and I spot-checked a sample of their findings by hand.

Sources that disagree

The most useful thing the research produced is a list of sources not to trust on their own, now in docs/data-review-pt.md:

gov.pt citizen-service pages sometimes show the district capital's holiday instead of the municipality's (Mortágua, Tabuaço, Pedrógão Grande, Portel), or a stale year.
The widely copied compiled list is wrong for several places and swaps the two Lagoas and the two Calhetas (each name exists twice, on different islands).
Some directories still show Alfândega da Fé's pre-2016 date. The câmara moved it from 29 June to 8 May, and its own page says so.

Then there are real conflicts, where official sources disagree with each other or with tradition. Nordeste in the Azores is one: older lists say 18 July, but the câmara's own festival programmes put the holiday on a Monday in mid-July. The data uses "the Monday on or before 18 July" and the note explains why.

Where it stands

From src/generated/data.json at the time of writing:

291 of 308 Portuguese municipal holidays are verified: 134 from IRN registry pages, 100 from gov.pt pages, 57 from câmara websites, the Diário da República and other official documents.
17 are still unverified, with secondary sources only. They're listed by name in the review doc. The fastest fix is usually an email to the câmara.
All of Portugal's national and regional holidays are verified, against the consolidated Labour Code and the regional decrees.

Keeping it up to date, without AI

Holidays change. A council votes to move its date, a page gets redesigned, a site goes down. So there's a script that re-checks every source: scripts/verify-sources.ts. It uses no AI. For each record it fetches source.url, strips the HTML, and looks for the saved quote.

Pages change formatting more often than content, so both sides are normalised first (accents, quotes, whitespace):

function normalize(s: string): string {
  return s
    .normalize("NFD")
    .replace(/\p{Diacritic}/gu, "")
    .toLowerCase()
    .replace(/[“”«»"']/g, "")
    .replace(/\s+/g, " ")
    .trim();
}

A quote can be shortened with "...", in which case every fragment of 15 characters or more must be on the page. Each record ends up in one bucket:

ok: the quote is still there
date_found: the quote is gone but the date ("13 de junho") is still on the page, usually a redesign
changed: neither found; for a fixed date, the holiday may have moved
broken: HTTP error, timeout or a bad certificate
unreadable: a PDF or a page rendered by JavaScript

The baseline run on 16 October 2026 gave 289 ok, 3 date_found, 22 unreadable, 8 changed (6 of them movable holidays, where the page just shows another year's date), 3 broken and 1 without a URL. The plan is to run it yearly and research only the changed and broken entries. That keeps maintenance to a handful of records a year instead of 308.

The other countries

Brazil, Germany, the UK, Greece and the US work differently. Their national and state layers are imported from python-holidays, so their source is the dataset, pinned to a version, and every record is unverified. Instead of quotes they get automatic cross-checks against two other open datasets. That process gets its own post: "Adding a new country: what it takes to go from 6 to 7".

Limitations

verified_at is when the source was checked, not a guarantee that it is still true today. That's what the yearly re-check is for.
PDFs and JavaScript-rendered pages are not checked automatically, so 22 records depend on a person looking.
The date fallback only works for fixed dates, and only in Portuguese ("13 de junho").
A registry page saying it closes on a day is strong evidence, but it's still not the municipal deliberation itself. Where the two might disagree, I'd rather show the quote and let you judge.

How do you handle provenance for reference data in your own projects? Do you store the source next to each record, or keep it somewhere else? I'd like to hear about it in the comments.

Next in the series: Business days that know local holidays.

hldays.dev · Docs

Building hldays #2: Modelling holidays from country down to municipality

Alexander Denisov — Thu, 29 Oct 2026 09:00:00 +0000

In part 1 I explained why I started hldays: I kept forgetting my municipal holiday, and found out that every Portuguese municipality has its own.

This post is about the first real problem: how do you model holidays so the same API works for Lisbon, Bavaria and Texas?

The naive version

My first mental model was a table:

date	name	country
2026-12-25	Christmas	PT

That breaks almost immediately:

Holidays aren't dates, they're rules. Christmas is "25 December". Good Friday is "two days before Easter". Thanksgiving is "fourth Thursday of November". You can't store 2016 to 2099 by hand.
Holidays aren't national. Bavaria has Epiphany, Berlin doesn't. Madeira has Madeira Day. Braga has São João on 24 June.
Places have different shapes. Portugal has districts, two autonomous regions and 308 municipalities. Germany has states. The US has states and territories.

So the model became two things: a tree of jurisdictions, and a set of rules attached to them.

1. A tree of jurisdictions

Every place is a jurisdiction with an id, a level and a parent:

PT country
├── PT-03 subdivision (district) Braga
│ └── PT-M-0303 municipality Braga
├── PT-11 subdivision (district) Lisboa
│ └── PT-M-1106 municipality Lisboa
├── PT-20 subdivision (autonomous_region) Azores
└── PT-30 subdivision (autonomous_region) Madeira

There are only three levels (country, subdivision, municipality), but each subdivision also has a kind (district, autonomous_region, state...). The levels keep the API predictable, and the kind keeps the local meaning.

Not every country uses every level. Right now Portugal, Germany and Brazil go down to municipalities. The UK and the US stop at subdivisions, and Greece is national only. Each country also says what its weekend is, because "business day" depends on it.

The ids follow ISO 3166 where it exists (PT, PT-03, DE-BY), with a municipality code for the extra level (PT-M-0303, from Portugal's official municipality code).

2. Holidays are inherited

The main idea is simple: a jurisdiction gets its own holidays plus everything from its parents.

Ask for Braga municipality and you get:

the 13 national public holidays from PT
São João on 24 June from PT-M-0303

Every holiday in the response says where it came from:

{
  "date": "2026-06-24",
  "holiday_id": "feriado-municipal",
  "name": { "pt": "São João Baptista" },
  "type": "local",
  "status": "verified",
  "source": {
    "url": "https://irn.justica.gov.pt/Contactos-do-Registo/Registo-Civil-de-Braga",
    "verified_at": "2026-10-16",
    "quote": "Encerrado no feriado municipal (24 de junho)"
  },
  "jurisdiction": { "id": "PT-M-0303", "name": "Braga", "level": "municipality" }
}

That jurisdiction field turned out to matter a lot. For Bavaria, Epiphany comes from DE-BY and Christmas from DE, so you can tell "this is a Bavarian holiday" apart from "this is a German holiday" without guessing.

Inheritance also needs an escape hatch for the day a place doesn't observe something its parent does (a US state that skips a federal holiday, say). A jurisdiction can list excludes: inherited holiday ids it skips. No place in the data needs it yet, but it's tested and ready.

The whole mechanism is small. Walk from the place up to its country, collect each level's holidays, and drop anything a more specific level has excluded. This is the real code from src/core/calendar.ts:

/** The jurisdiction followed by its ancestors up to the country. */
chain(j: Jurisdiction): Jurisdiction[] {
  const out: Jurisdiction[] = [];
  for (let cur: Jurisdiction | undefined = j; cur; cur = cur.parent ? this.byId.get(cur.parent) : undefined) {
    out.push(cur);
  }
  return out;
}

/** Own + inherited occurrences, minus inherited holidays a descendant in the chain `excludes`. */
private resolved(j: Jurisdiction, year: number, municipal: boolean, includeSelf = true): Occurrence[] {
  const out: Occurrence[] = [];
  const excluded = new Set<string>();
  for (const x of this.chain(j)) {
    if ((includeSelf || x !== j) && (municipal || x.level !== "municipality"))
      out.push(...this.own(x, year).filter((o) => !excluded.has(o.holiday_id)));
    for (const id of x.excludes ?? []) excluded.add(id);
  }
  return out;
}

The municipal flag is also where the free plan is enforced: with municipal: false the walk simply skips the municipality level, so the same code serves both plans.

3. Rules, not dates

hldays stores 716 holiday rules, not dates. When you ask for a year (anything from 2016 to 2099), the rules are expanded into concrete dates.

The data lives in YAML files in the repo. This is Braga's entire entry:

- id: PT-M-0303
  country: PT
  level: municipality
  name: "Braga"
  parent: PT-03
  codes: { ine: "0303" }
  holidays:
    - id: feriado-municipal
      name: { pt: "São João Baptista" }
      type: local
      rule: { fixed: "06-24" }
      status: verified
      source: { url: "https://irn.justica.gov.pt/Contactos-do-Registo/Registo-Civil-de-Braga", verified_at: "2026-10-16", quote: "Encerrado no feriado municipal (24 de junho)" }

A rule has exactly one shape. These are the real ones, from src/core/types.ts:

export type Rule =
  | { fixed: string } // "MM-DD"
  | { easter: number } // offset in days from Easter Sunday (Gregorian)
  | { nth_weekday: { month: number; weekday: number; n: number; offset?: number } } // n=-1 is last
  | { on_or_before: { date: string; weekday: number } } // that weekday on or before "MM-DD"
  | { dates: string[] } // explicit "YYYY-MM-DD" list, for holidays decreed year by year
  | { orthodox_easter: number } // offset in days from Orthodox (Julian) Easter Sunday
  | { calendar_date: CalendarDate }; // a day in a non-Gregorian calendar

In practice, three of them do most of the work: fixed (437 rules), nth_weekday (135) and easter (105). Corpus Christi in Portugal is { easter: 60 }, Memorial Day in the US is the last Monday of May (n: -1), and a municipality whose holiday is "the Monday after the first Sunday of October" is nth_weekday with an offset of 1. The odd ones exist because real holidays needed them: dates covers holidays that a government decrees one year at a time, and orthodox_easter is for Greece.

Two more fields sit next to the rule:

substitute : what happens when the date falls on a weekend. US federal holidays move a Saturday to the Friday before and a Sunday to the Monday after. In 2026, 4 July is a Saturday, so the US response lists both 4 July and Friday 3 July, the second one with "substitute_for": "2026-07-04".
valid_from / valid_to : holidays get added and removed by law. Brazil's National Day of Zumbi and Black Awareness (20 November) became a national holiday in 2024, so it has valid_from: 2024, while the state-level versions that existed before end with valid_to: 2023. 95 rules have a range like this.

Portugal has its own famous case: four national holidays were suspended between 2013 and 2015 and restored in 2016. The API's range starts in 2016, so that one never needs a range at all.

4. Types and status

Every holiday also carries two fields that I now consider essential:

type : public (a day off by law), local (a municipal holiday, observed by public services and optional for some private employers) or optional (a day off only by agreement or government decision, like Carnival in Portugal). By default the API returns public and local.
status : verified or unverified. A holiday is only verified when it's backed by an official source, with a URL and the date it was checked. That's the topic of the next post.

Right now Portugal has 309 of 326 rules verified. The other countries are still unverified, and the API says so instead of hiding it.

5. Names are harder than dates

"Braga" is both a district (PT-03) and a municipality (PT-M-0303). Searching for it returns both:

curl "https://api.hldays.dev/v1/jurisdictions?q=braga"


{ "data": [
  { "id": "PT-M-0303", "name": "Braga", "level": "municipality", "country": "PT", "parent": "PT-03" },
  { "id": "PT-03", "name": "Braga", "level": "subdivision", "kind": "district", "country": "PT", "parent": "PT" },
  { "id": "PT-M-0402", "name": "Bragança", "level": "municipality", "country": "PT", "parent": "PT-04" },
  { "id": "PT-04", "name": "Bragança", "level": "subdivision", "kind": "district", "country": "PT", "parent": "PT" }
]}

So the holiday endpoints accept a name (jurisdiction=lisboa or jurisdiction=Lisbon) and prefer the most specific level. Search ignores accents, aliases cover English names, and a country parameter resolves names that exist in more than one country. There's a whole post on this later in the series.

Holiday names are stored per language ({ "pt": "Ano Novo", "en": "New Year's Day" }): the official name first, plus English where I have it. National holidays have both; the municipal ones only have their Portuguese name so far.

What I'd tell myself at the start

Model the places before the holidays. Once the jurisdiction tree was right, inheritance was almost free.
Store rules, generate dates. It's less data, it covers every year, and changes in the law become a date range instead of a migration.
Always say where a value came from. The jurisdiction on each holiday, and the source, made the data easier to trust and easier to debug.

Next time: a source on every record, and how I collect, verify and keep 300+ municipal holidays up to date.

hldays.dev · Docs

Building hldays #1: I kept forgetting my municipal holiday, so I built an API for it

Alexander Denisov — Fri, 23 Oct 2026 09:00:00 +0000

At work I get one extra day off a year: my municipality's holiday.

Every year I forgot about it.

That was the whole problem at first. But when I looked into it, I found something more interesting: every municipality has its own holiday. Lisbon's is on 13 June, Porto's on 24 June, Coimbra's on 4 July. Portugal has 308 municipalities, and each one sets its own local holiday on top of the national ones.

I wanted to understand how that worked. Then I wanted to see if I could organise it properly. That turned into hldays.

What hldays is

hldays is a public holidays API that goes down to the municipality :

National, regional and municipal holidays in one API
A source on every record : each holiday links to the law, registry or council page it comes from, with a quote and the date it was checked
Business-day maths that knows local holidays : "Is this a working day in Porto?" or "What's 10 business days from today in Braga?" is one call
REST and MCP : the same data is available to apps and to AI agents like Claude

Getting national holidays for a country needs no key:

curl "https://api.hldays.dev/v1/holidays?jurisdiction=PT&year=2026"

A single municipality (Braga here) uses the same call. Without a key you get the national and regional holidays that apply there, plus a notice; Braga's own holiday comes with a paid plan:

curl "https://api.hldays.dev/v1/holidays?jurisdiction=PT-M-0303&year=2026"

Where it is today

The site is live at hldays.dev, with docs and the API at api.hldays.dev.

At the time of writing it covers 6 countries (Portugal, Brazil, Germany, the UK, Greece and the US): 440 places and 716 holiday rules. Portugal is the most complete: all 308 municipal holidays, nearly all of them verified against an official source. For the other countries, verification is still to come.

National and regional data is free (rate limited). Municipal holidays and religious/cultural observances are on paid plans through RapidAPI.

It still has limitations, and I'll be honest about them as the series goes on.

Why I kept going

The first goal was to stop forgetting one day off. What kept me going was the engineering:

Data modelling. How do you represent "the Tuesday after Easter in this municipality" next to "25 April, nationwide", across countries with different hierarchies?
Maintenance. Holidays change. Laws are amended, councils move dates. What does it take to keep this data correct and prove where every record came from?
Working with it. Business-day calculations sound simple until local holidays get involved.
Shipping it. Docs, pricing, rate limits, and getting a side project in front of people.
Agents. How do you expose data so an AI agent can use it reliably? That's why hldays has an MCP server.

I learned more from this side project than I expected, so I'm going to write it down.

What's next in this series

Here's the rough plan:

This post : why hldays exists
Modelling holidays : jurisdictions, rules, and the layers from country to municipality
A source on every record : how the data is collected, verified and kept fresh
Business days that know local holidays : weekends, observed days, adding and subtracting business days
Observed holidays and edge cases : weekend shifts and changes in the law
Names are harder than dates : same-name places, aliases and accent-insensitive search
Religious and cultural observances : Easter, Orthodox, Jewish, Islamic and Chinese calendars
Making an API agent-friendly with MCP
The architecture : TypeScript on Cloudflare Workers, with no database
Docs that sell the API : OpenAPI, Redoc and the homepage demo
Shipping and monetising a side-project API : free vs paid tiers, RapidAPI, rate limits
Adding a new country : what it takes to go from 6 to 7
Lessons learned so far

If you've ever had to deal with holidays in code, or you have a municipal holiday you always forget, I'd love to hear about it in the comments. Feedback on the API is very welcome too.

hldays.dev · Docs