I still remember where i was when the email came in.
December 25th. Christmas morning. Phone in hand while having breakfast, and there is an email from our client's CTO. No greetings, Just
"We're terminating the contract. Our legal team will be in touch"
We lost a 120K a year contract. On a Christmas morning because of a date calculation bug that none of us, not a person on a team of 5 experienced developers had ever experienced.
Here's what happened
The file nobody wanted to touch
Every engineering team I've ever been on had a file similar to this. Ours was business_day_utils.py. It was 1,847 lines long and had a comment at the top that read:
# WARNING: Do not refactor. Do not "improve". Do not touch.
# This file has been through 3 rewrites. All 3 failed.
# If you think you understand it, you don't.
# - James, 2021
It handled our SLA deadline calculations for a Fintech client operating across Germany, the Netherlands and Saudi Arabia. It had bugs, we knew it had bugs. We just didn't know where they were.
The file calculated business days. Simple enough, right? Skip weekends, skip public holidays and return the correct datetime. Every calendar library we used agreed. Every timezone check passed, the unit tests passed. The staging environment looked fine.
On December 24th, 2022, our system calculated that a batch of payment overdue notices should go out that afternoon. 50,000 of them to customers of a German bank.
The calculation was correct by every measure we had. Except one.
What no library told us
In German banking, December 24th Heiligabend, Christmas Eve ends at noon
Not a public holiday, not a weekend. A half day. It's documented in the Bundesbank TARGET2 closure calendar. A PDF in German. On the Bundesbank website, something that is apparently common knowledge in German banking circles and completely invisible to every date library, every timezone package and every "Business Days" function ever written.
Our system didn't know, so it sent the notices.
50,000 wrong SLA breach notifications went to customers of a German bank on a day that, in German banking had effectively ended at 12pm.
The bank's CTO found out that evening. The termination email arrived the next morning.
We found out on Christmas Day.
The week after
I spent the week between Christmas and New year doing one thing: looking for a solution that would have prevented this.
I needed something that knew:
National public holidays(Obviously)
Sub national holidays: Bavaria has different public holidays than Berlin . Most libraries treat "Germany" as a single thing. It isn't
Half days: Christmas Eve in German banking, New Year's Eve in German banking and NYSE early close days. These exist, they matter and nobody covers them.
The Gulf work week: Saudi Arabia, UAE, Qatar all use Friday/Saturday as their weekend, not Saturday/Sunday. Also, Saudi Arabia changed its weekend on June 29th 2013, from Thursday/Friday to Friday/Saturday. Royal Decree M/46. Most libraries I tested in 2022 still had the wrong dates.
Substitute holidays: When a holiday falls on a weekend, the observed day shifts. Different countries handle this differently. Japan's rules are particularly complicated.
DST-safe arithmetic: Adding "8 business hours" across a clock change boundary is not the same as adding 8 * 3600 seconds. We'd been getting this wrong too, we just hadn't caught it yet.
An audit trail: Something I could actually show a lawyer or a compliance officer that explained exactly why a deadline was calculated the way it was.
I found nothing that did all of this. I found things that did some of it. I found libraries that required me to maintain the holiday database myself (the whole problem). I found APIs that covered 60 countries with no sub-national support.
I didn't find what I was looking for.
So I built it
I want to be honest about something. I didn't build this because I had a great product idea. I built it because I was angry and embarrassed and I never wanted to be responsible for a situation like that again.
A global business day API. One endpoint. You POST a datetime, a jurisdiction, and an offset. You get back the resolved datetime plus a complete audit trail of everything that was skipped and why.
This is what the response looked like for the exact call that would have saved us:
POST /v1/resolve
{
"from": "2024-12-24T09:00:00Z",
"timezone": "Europe/Berlin",
"jurisdiction": "DE/BY",
"add_business_hours": 8,
"calendar": "banking"
}
{
"result": "2024-12-27T13:00:00+01:00",
"skipped": [
{
"date": "2024-12-24",
"reason": "Heiligabend — banking half-day",
"type": "half_day",
"hours_lost": 4.0,
"source": "https://www.bundesbank.de/en/tasks/payment-systems/target2/calendar"
},
{
"date": "2024-12-25",
"reason": "Christmas Day",
"type": "public_holiday",
"source": "https://www.bmi.bund.de/feiertage"
},
{
"date": "2024-12-26",
"reason": "Boxing Day",
"type": "public_holiday",
"source": "https://www.bmi.bund.de/feiertage"
}
],
"jurisdiction_verified": true,
"engine_version": "2025-04"
}
See that source field? That's the Bundesbank calendar. The actual government document. In the API response. So if anyone ever asks why your SLA deadline was calculated the way it was, you have a timestamped JSON record pointing to the official source.
That field alone would have saved our contract.
What it covers
I'll be honest, building this was not fun. Maintaining verified holiday data for 150 countries across different government publication formats, in different languages, with different update schedules, it's an unglamorous data operation that never ends. Governments change dates. Parliaments pass new legislation. The Saudi weekend switch in 2013 that I mentioned, most libraries still get that wrong in 2026 because nobody is maintaining the data seriously.
Here's what's currently covered:
150 countries: National calendars
All 50 US states: Texas Independence Day is March 2nd and it matters if your customer is a Texas government contractor
German Länder: Bavaria, Berlin, NRW, Hamburg, all of them, separately
Swiss cantons: Geneva and Zurich have different rules
Australian states: Queensland and Victoria are different
Canadian provinces: Ontario and Quebec are different
Gulf states: Saudi Arabia, UAE, Qatar, Bahrain, Kuwait: Friday/Saturday work week with the correct 2013 cutover date
Islamic holidays: Eid al-Fitr, Eid al-Adha, Islamic New Year pre-computed through 2040
Industry calendars: Banking, NYSE, LSE, TSX, healthcare, logistics, government
Half days: Heiligabend, Silvester (German banking), NYSE July 3rd early close, NYSE day after Thanksgiving, LSE Christmas Eve and New Year's Eve
Substitute holidays: When holidays fall on weekends, computed correctly per jurisdiction
DST safe arithmetic: Minute level precision across clock changes
Stateless. No database. The full dataset compiles into memory at startup.
Integrating takes 3 lines
Python
import httpx
r = httpx.post(
"https://business-datetime-resolution-api.p.rapidapi.com/resolve",
json={
"from": "2024-12-24T09:00:00Z",
"timezone": "Europe/Berlin",
"jurisdiction": "DE/BY",
"add_business_hours": 8,
"calendar": "banking"
},
headers={
"X-RapidAPI-Key": "YOUR_KEY",
"Content-Type": "application/json"
}
)
print(r.json()["result"])
# → "2024-12-27T13:00:00+01:00"
or JavaScript
const r = await fetch("https://business-datetime-resolution-api.p.rapidapi.com/resolve", {
method: "POST",
headers: {
"X-RapidAPI-Key": "YOUR_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
from: "2024-12-24T09:00:00Z",
timezone: "Europe/Berlin",
jurisdiction: "DE/BY",
add_business_hours: 8,
calendar: "banking"
})
});
const { result } = await r.json();
It's on RapidAPI with a free tier. 500 calls per month, no card required. After that it's $0.003 per call. A developer running 10,000 calls per month pays $30. For a mid-size SaaS processing 100,000 transactions per day, it's less than one junior engineer's weekly salary.
→ Get your free API key on RapidAPI
The thing I keep thinking about
Building this, I spoke to maybe 40 or 50 developers about business day calculations. The stories I heard were extraordinary.
One engineer told me about a payroll system that paid employees on a Saudi national holiday for three years before anyone noticed. Another described a logistics platform that had been showing wrong delivery ETAs every December for five years, they'd just gotten used to the customer service spike.
The most common thing I heard was some version of: "We have a file for that. Nobody touches it."
Every company has the file. The file is never fully correct. Nobody wants to fix the file because the last person who tried is no longer employed there.
I built the API so the file can die.
Edge cases I learned the hard way
A few things that surprised me during the build, in case they're useful:
Japan's substitute holiday system is uniquely complicated. Japan has "substitute holidays" (振替休日) when a public holiday falls on Sunday, but it also has "citizens' holidays" (国民の祝日) when a regular day gets squeezed between two public holidays. The rules for this have changed multiple times since 1985.
Saudi Arabia's work week changed mid year in 2013. Royal Decree M/46, effective June 29th, 2013. Before that date, the weekend was Thursday/Friday. After, it became Friday/Saturday. If you're calculating a business deadline that straddles that date which is unlikely but not impossible for multi-year contracts you need to know the exact cutover.
Christmas Eve in German banking is a partial day, not a full holiday. This is documented in the Bundesbank's TARGET2 calendar. The TARGET2 payment system closes at noon on December 24th. Most date libraries do not know this exists. We learned this the way I described above.
NSW and Queensland have different public holidays on the same day sometimes. Australia Day (January 26th) observance varies by state. When it falls on a weekend, each state independently decides when to observe it.
DST transitions in the US happen at 2am local time. Adding "8 business hours" starting at 11pm on the night before a spring forward results in an ambiguous calculation that most libraries handle incorrectly.
One last thing
If you've read this far and you're thinking "we have a file like this". I'd genuinely like to hear about it. I'm just collecting edge cases and some of the ones I've heard are remarkable.
Drop a comment below. And if the API is useful, it's at the link above.
I'm sorry it took losing a $120k contract to build it. I'm glad it exists now.
API is available on RapidAPI. Free tier: 500 calls/month. No card required.→ Get your free API key on RapidAPI