Add business days to a date

Add business days with the API

Use GET /v1/calendars/holidays/{country}/{year} to get the holiday dates for the country and year your calculation needs. The Python function keeps those dates in a set and compares each date in the walk against it. A date counts only when it is a weekday and is absent from the holiday set. Skipped dates leave the remaining business-day count unchanged.

1. Set your API key Get a free API key and keep it in the environment variable NARWHAL_API_KEY. The script reads that variable and sends the key as Authorization: Bearer YOUR_KEY to https://api.narwhalapi.com.
2. Choose the start date and country Pass the start date, the business days to add and the country's code to add_business_days; the function defaults to USA. The start date is day 0, so the function moves forward before deciding whether a date counts toward the total.
3. Run the calculation For Friday 20 November 2026 plus five business days in the United States, use the call at the end of the script. It prints 2026-11-30, after skipping the weekends and Thanksgiving on Thursday 26 November 2026.
   Python, add business days to a date

   import os
   from datetime import date, timedelta
   import requests
   
   API = "https://api.narwhalapi.com"
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   def holidays(country: str, year: int) -> set[str]:
       r = requests.get(f"{API}/v1/calendars/holidays/{country}/{year}", headers=HEADERS, timeout=10)
       r.raise_for_status()
       return {h["date"] for h in r.json()["holidays"]}
   
   def add_business_days(start: date, n: int, country: str = "USA") -> date:
       off, loaded, day = set(), set(), start
       while n > 0:
           day += timedelta(1)
           if day.year not in loaded:
               off |= holidays(country, day.year)
               loaded.add(day.year)
           if day.weekday() < 5 and day.isoformat() not in off:
               n -= 1
       return day
   
   print(add_business_days(date(2026, 11, 20), 5))

Each year is loaded only once during a calculation. When the walk crosses 1 January, the function requests the holiday calendar for that year before it counts any dates there. The loaded set records which years it already has, while off holds their holiday dates. The walk continues until the requested business-day count has been used up, then returns the date it reached.

The holidays function reads the response's holidays array and takes the date from each entry. The walk compares those values with day.isoformat(), while day.weekday() supplies the weekday condition. Both conditions must pass before n decreases. A holiday that falls on a weekend is still a skipped date: the loop advances by a calendar day each time, and that date cannot reduce the remaining count. The return value is the date reached when the count is complete.

Use Excel or Google Sheets

In Excel or Google Sheets, put 26 November 2026 in the range named Holidays and use WORKDAY with your start date and business-day count. For Friday 20 November 2026 plus five business days, the formula returns 30 November 2026. The holiday range supplies the dates to skip along with weekends, so include the holiday dates that apply to your calculation.

=WORKDAY(DATE(2026,11,20), 5, Holidays)

Format the result cell as a date. WORKDAY returns a serial number, so the cell's date format is what makes the result appear as a calendar date. Use WORKDAY.INTL when your calculation needs other weekends. Keep the start date, business-day count and holiday range matched to the calculation you want; the formula uses the holiday dates you supply. In the example formula, DATE(2026,11,20) supplies the start date and 5 supplies the business-day count. Holidays refers to the range that holds 26 November 2026. To use the sheet for another start date, change the start-date input and supply the applicable holidays.

Which option to use when

What if the start date is a holiday or weekend?

Day 1 is the first business day after the start date. Saturday 28 November 2026 plus one business day is Monday 30 November 2026: Sunday is skipped, and Monday supplies the business day you asked to add. The same rule applies when the start date itself is a holiday. Counting begins after that date, with weekends and holiday dates skipped along the way.

Can I subtract business days?

Yes. Walk backwards with timedelta(-1), skipping weekends and holiday dates, or use =WORKDAY(start, -5, Holidays) in a sheet. That formula subtracts five business days from the start date using the supplied holiday range. For Python, apply the backwards rule when adapting the function; the supplied script walks forwards.

What if the year has no published holiday calendar?

The API returns 404 calendar_not_published for that country and year. The script's raise_for_status() raises an error for that response, so the supplied function stops there. You can adapt it to use weekends only and flag the result, or retry later. If you use the weekends-only route, flag the returned date so the calculation's treatment of holidays remains clear.

Worked example: 5 business days after Friday 20 November 2026

Start with Friday 20 November 2026 as day 0. Skip the weekend, then count Monday 23 November, Tuesday 24 November and Wednesday 25 November as business days 1, 2 and 3. Thursday 26 November is Thanksgiving in the United States, so the count stays at 3. Friday 27 November supplies business day 4.

Skip Saturday 28 and Sunday 29 November 2026. Monday 30 November is business day 5, giving the result 2026-11-30. Without the Thanksgiving holiday, Thursday 26 November would count as business day 4 and Friday 27 November would be business day 5, giving Friday 27 November 2026 instead.