Business Day Calculator in Python: Add Working Days with Holidays and Closures

Business Day Calculator in Python: Add Working Days with Holidays and Closures

01Introduction

An order arrives on December 23 with a promise to dispatch within three business days. Adding three calendar days gives you December 26. A loop that skips Saturday and Sunday does better, but still misses Christmas. A company shutdown adds another rule.

The date calculation needs a calendar as well as a number.

We'll build a small Python example with Calculate Business Days Across Countries and Markets on ApyHub, a business day calculator API. We build this service at Callable Labs. The goal is a deadline your application can explain: which date it chose, which calendar it used and which closures it skipped.

02Define what the promise means

Before writing the request, choose the start date and calendar. For this example, the start is December 23, 2026, the calendar is Germany and the company also closes on December 28.

The add operation excludes the start date from its count. If your order policy counts the order day when it arrives before a cutoff time, apply that policy before requesting the deadline. The API handles dates; your application handles the local time zone and order cutoff.

03Request the deadline

Install requests with python -m pip install requests, set APY_TOKEN to your ApyHub API key and run:

import json
import os
from pathlib import Path

import requests

URL = (
    "https://api.eu.apyhub.com/callable-labs/"
    "calculate-business-days-across-countries-markets-api/v1/business-days/add"
)
parameters = {
    "start": "2026-12-23",
    "days": 3,
    "country": "DE",
    "exclude": "2026-12-28",
}
response = requests.get(
    URL,
    headers={"apy-token": os.environ["APY_TOKEN"]},
    params=parameters,
    timeout=30,
)
response.raise_for_status()
result = response.json()
print("Dispatch by:", result["date"])
for skipped in result["skipped_holidays"]:
    print(skipped["date"], skipped["reason"], ", ".join(skipped["names"]))

record = {"request": parameters, "response": result}
Path("dispatch-deadline.json").write_text(
    json.dumps(record, ensure_ascii=False, indent=2), encoding="utf-8"
)

Under the service's German public-holiday calendar and this extra closure, the three counted working days are December 24, 29 and 30. The deadline is December 30. The skipped_holidays field explains holiday and custom-closure skips; ordinary weekends are not listed in that field.

Saving the request with the response records the extra company closure as well as the returned calendar settings and calendar_version. That makes a later customer question easier to investigate than a bare date in a database.

04Choose the calendar that matches the work

For regional holidays, add a supported subdivision, such as BY for Bavaria. Country reference data exposes the available regions. For an exchange-specific schedule, use market instead of country; send exactly one of those selectors. Filling both is an invalid request.

Keep company closures in exclude. Override weekend only when your operating schedule requires it, such as fri,sat. Selecting an exchange calendar does not model every step of a securities settlement process, and selecting a country's calendar does not establish a carrier's actual delivery schedule.

If your application displays holidays, use the separate Public Holidays API. A visible holiday list and a calculated working-day deadline serve different parts of the user experience.

05Count a range with the right boundary rules

The same business-days service offers /v1/business-days/count and /v1/business-days/next. Count includes both the start and end dates. Add excludes the start date. Those different boundary rules matter when a report compares "working days in this period" with "five working days after this event."

Use an explicit start date in scheduled jobs. An omitted date defaults to today in UTC, which can differ from the business date where an order was placed. Keep returned values as calendar dates when displaying them; converting midnight through a time zone can shift the visible day.

For a 422 response, correct the named input. For a temporary failure, use bounded retries and honor Retry-After; check account limits before retrying a 429. Calls and retries can consume atoms (ApyHub's usage unit). Review exceptional holiday announcements when a date has significant consequences.

06Give an AI agent a real calendar

Agents are bad at holiday math when they work it out themselves. Through ApyHub MCP, an agent in Claude, ChatGPT, Cursor or any MCP client can call this business days API directly, like every endpoint in the ApyHub catalog, without a wrapper or tool definition. It gets the same calendar-backed answer every time and spends fewer tokens than writing date logic on the fly.

Connect ApyHub MCP to your agent →

07Conclusion

Try the business-days playground with a deadline that crosses one of your own closures. A useful first integration should return both the date and enough context to explain it.

Try the Business Days API for free →

08FAQ

How do I add business days excluding holidays in Python? Call /v1/business-days/add with days, start and a country or market, as in the script above. The response gives the resulting date and every holiday and closure it skipped.

Does adding business days count the start date? No. Add starts counting the day after start. Count includes both the start and end dates.

How do I count business days between two dates? Use /v1/business-days/count with start and end. It handles ranges of up to ten years and lists the holidays that fell on weekdays.

Can I include regional holidays or company shutdowns? Yes. Use subdivision (for example BY for Bavaria) for regional holidays and exclude for shutdown dates.

Does it support stock exchange calendars? Yes. Send market (for example XNYS) instead of country, never both.

How do I test the business days API before writing code? Use the playground on the API page, run the request with curl, or save it in Voiden, an open-source API client that stores requests as Markdown files next to your code.

Is there a free plan? Yes. The ApyHub Starter plan includes 5 API calls a day and 3,000 atoms a month, with no credit card.

09About Callable Labs

Callable Labs builds APIs for machine-readable workflows, designed for automation and AI agents. Besides the business days calculator, their APIs on ApyHub include:

• Public holidays by country and stock market and stock exchange calendars
• ECB exchange rates and an ECB currency converter
• Invoice generation and e-invoice validation
• OCR from images and PDFs to Markdown

See all 20 on the Callable Labs provider page.

10About ApyHub

ApyHub is a curated API catalog and trusted operational layer for developers and AI agents. The catalog has over 1,500 endpoints and capabilities and keeps growing, all under one subscription billed in atoms. Every service carries machine-readable certification (GDPR, SOC 2, ISO 27001), is MCP-ready by default and runs in dedicated EU and US regions. More than 65,000 developer workspaces use ApyHub every month, and the free tier needs no credit card. Have an API of your own? Publish it on ApyHub.