Building hldays #1: I kept forgetting my municipal holiday, so I built an API for it
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.