Blog
Notes from building a holiday API: where the data comes from, what the calendars get wrong, and how it runs.
-
Building hldays #13: Lessons learned so far
What building a municipal holidays API taught me: about data sources, calendars, tooling, shipping, and what I'd do differently.
-
Building hldays #12: Adding a new country
What it takes to go from 6 countries to 7: importing python-holidays as rules, checking the engine against it, cross-checking two other datasets, and the part that can't be imported.
-
Building hldays #11: Shipping and monetising a side-project API
What's free in hldays and what's paid, how plan gating works in a Cloudflare Worker, selling through RapidAPI, and the anonymous tier with a per-IP rate limit.
-
Building hldays #10: Docs that sell the API
One endpoint list in TypeScript drives the API index, the OpenAPI spec, the Redoc docs and the RapidAPI listing. Plus a live search demo and responses that explain themselves.
-
Building hldays #9: The architecture, TypeScript on Cloudflare Workers
How hldays is served: a Hono app on Cloudflare Workers, YAML data compiled into the bundle with no database, and a second Worker for the site.
-
Building hldays #8: Making an API agent-friendly with MCP
How hldays exposes its holidays API to Claude and other agents over MCP: seven tools, each one a thin wrapper over a REST route, with the same auth and plans.
-
Building hldays #7: Religious and cultural observances
Easter, Orthodox Easter, Hebrew and Islamic dates through Intl, and a Chinese calendar from Hong Kong Observatory tables because ICU is a day off on Chinese New Year 2027.
-
Building hldays #6: Names are harder than dates
Two Lagoas, two Calhetas, a Braga that is both a district and a city, and São Paulo twice. How hldays turns a place name into the right jurisdiction.
-
Building hldays #5: Observed holidays and edge cases
Weekend shifts that cross New Year, holidays that move to Friday, laws that change mid-decade, and the Portuguese holidays that disappeared for three years.
-
Building hldays #4: Business days that know local holidays
Is 24 June a working day in Porto? How hldays answers business-day questions with weekends, substitute days and municipal holidays, and where the edges are.
-
Building hldays #3: A source on every record
How hldays collects holiday data, what it takes for a record to count as verified, and the script that re-checks every source without AI.
-
Building hldays #2: Modelling holidays from country down to municipality
A tree of jurisdictions, inheritance, and rules instead of dates: how one model covers Lisbon, Bavaria and Texas.
-
Building hldays #1: I kept forgetting my municipal holiday, so I built an API for it
Portugal's 308 municipalities each set their own holiday. Why I turned that into a public holidays API with a source on every record, and what this series will cover.
Follow along with the RSS feed.