Public holidays and out-of-office spans: import holidays and show the reason on the booking calendar

[jacomv]

Problem

1. No holiday support. Hosts have to add a day_off override for every public holiday, every year, by hand.
2. On the booking page, every unavailable date looks the same. A holiday, a multi-day out-of-office span and a fully booked day all show as the same greyed-out number, so a booker can't tell "away until the 31st" from "no times left".

Proposal

• Holidays. Add a per-host holiday_country setting (ISO 3166-1). Resolve the dates on the server (Nager.Date or Google's public holiday calendars), treat them as unavailable in slot generation, and let the host opt out of individual holidays. Cal.com has an equivalent per-user holiday setting.
• Unavailability reasons. Return them with the month's slots, e.g.

  "unavailable": [{ "date": "2026-11-02", "kind": "holiday", "label": "Día de los Santos" },
                  { "date": "2026-10-28", "kind": "out_of_office", "span": "start" }]

  span is one of single | start | middle | end, derived from the override's group_id. The booking page can then show an icon and a tooltip for a holiday, and draw an out-of-office range as one span with a start and an end marker.
• Privacy. Holiday names are public data. For out-of-office ranges, only show the reason or note if the host turns that on (Cal.com: showNotePublicly).

Current workaround

I'm doing this today with head_html injection plus a cron job that syncs holidays from Nager.Date into availability-overrides and generates a date → icon map. It works, but it's fragile:

• disabled day buttons carry no data-ds, so the script has to work out the date from the localized #month-label;
• any template change will break it.

Happy to test.

[shockalotti]

Thanks, this is well scoped. Two useful facts first: availability_overrides already carries reason (day_off / custom_hours, migration 00009) and group_id (00048), so the span idea maps onto columns that exist rather than needing new schema. And you are right that the current workaround is fragile for exactly the reason you give.

The open question I would like your view on is the holiday source, because it decides the shape of the whole feature.

Both options you mention are outbound network calls. Calnode's rule is that a stock instance needs no external services to run, and slot generation is on the critical path for every page load, so a holiday lookup that can hang or time out means a booking calendar that can hang or time out. Someone running this air-gapped should not get a site that half works.

So which do you picture:

1. A bundled dataset shipped inside the binary, refreshed with releases, no network at runtime. Predictable and offline-safe, but holidays change more often than we cut releases, and the dataset has to cover observed or substitute days correctly.
2. Fetched once into the database by the background worker, then read locally. Keeps the booking path offline-safe and lets people refresh without upgrading, at the cost of a new cache table and a refresh policy.
3. Fetch on demand, falling back to "no holidays known" when the call fails.

My preference is (1) or (2), and I would want to know which before building.

If it is a bundled dataset, which one, and what is its licence? Subdivision coverage matters more than it sounds: Germany needs the Länder, Spain the autonomous communities, and a country-level table will confidently mark the wrong days off. If it is fetched, which source and endpoint, and what should happen for an instance with no egress?

The other bits I agree with: only holiday names are public data, and the out-of-office label should be off unless the host turns it on. Your /v1/... slots payload addition is the right place for the reasons, since agents and the assistant already consume that endpoint and must keep receiving only bookable times.

If you end up wanting to build it rather than just test, say so and we can cut it down to a first slice. Testing on your setup is valuable either way.

[jacomv]

Thanks for the thoughtful reply, and for pointing out that reason and group_id are already there. That makes the span part much simpler than I expected.

On the source, I agree the booking path should never wait on a third party, so I'd go with (2). I'd also split the work so the core doesn't depend on any source at all.

A first slice could add a holiday reason with a label to the overrides and return the unavailable dates with their kind, label and span in the slots payload. Holidays would come in through the existing overrides API, entered by hand or by a script. That already works without egress and covers everything the booking page needs. It's essentially what I run today, without the DOM scraping.

A second slice could then have the background worker import holidays into that same table: a country per host, an optional ISO 3166-2 subdivision, the current and next year, and the last good data kept if a fetch fails. With no egress the import simply doesn't run.

For the fetcher, Nager.Date seems like a reasonable default. The code is MIT, it covers about 200 countries with subdivisions, and the API needs no key. Their offline variants require a sponsor licence, so it couldn't be bundled. If a bundled dataset is ever preferred, python-holidays (vacanza/holidays, MIT) looks like the stronger base. It has wider coverage and handles observed and substitute days well; Colombia's move-to-Monday rule would be a good test case.

I'd be glad to test the first slice on my instance (Colombia, Spanish UI, multi-day out-of-office spans). Thanks again for considering it.