Is there a working days API?
Not as one call, on any provider in the table. A working-days or business-days API is a holiday API plus a small count: weekdays in your range, minus the public holidays that fall on them. The part that goes wrong is the holiday list: observed days, regional holidays and years that cross a boundary.
The formula
- Working days = weekdays from start to end (both included) minus public holidays that fall on a weekday.
- One request per country and year. A range that crosses a year needs both years.
- Check which holidays are national and which are regional before you use the list for payroll.
Python function using Narwhal
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, year):
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 working_days(start, end, country="USA"):
off = set()
for year in range(start.year, end.year + 1):
off |= holidays(country, year)
days = (start + timedelta(n) for n in range((end - start).days + 1))
return sum(1 for d in days if d.weekday() < 5 and d.isoformat() not in off)
print(working_days(date(2026, 12, 1), date(2026, 12, 31))) # 22 in the United StatesFor 1 to 31 December 2026 in the United States this prints 22: 23 weekdays minus Christmas Day. The full walk-through, with a spreadsheet version, is in the how-to on counting business days between two dates (/how-to/count-business-days-between-two-dates).
The easy Narwhal call
The holiday list is one call, with observed days handled and a coverage note for the country. Narwhal has no business-day endpoint, so the count stays in your code.
A free Narwhal key comes with $10 of credit every month for the first 12 months, no card. After that a call costs $2 per 1,000 ($10 per 1,000 for company and filings data).
# Change: URL and key
url="https://api.narwhalapi.com"
url="$url/v1/calendars/holidays/USA/2026"
curl \
"$url" \
-H "Authorization: Bearer YOUR_API_KEY"Provider shortlist
Every figure comes from the vendor's own pages, read on 3 November 2026. Who is paid what on a holiday comes from labour law and your contracts, and no API answers that. This page is published by Narwhal.
Narwhal API
Payroll in the 91 covered countries, when FX, economics or MCP share the same key.
Calendarific
A cheap monthly start with regional detail and holiday types across a very wide country list.
HolidayAPI
Multi-country payroll that needs observed dates, workday math and the right to keep results.
Nager.Date
Prototypes and internal tools where a free hosted API with no key and no stated rate limit is enough.
Abstract API
Teams already on other Abstract APIs that want one holiday endpoint with regional entries.
date-holidays
Node.js payroll engines that want holiday rules in process, with no quota and no network call.
Federal Reserve Financial Services
Shifting US direct-deposit pay dates around days when the Reserve Banks are closed.
Compare the options
Best fit is not feature parity. Check the evidence and limitation together.
| Provider | Best for | Evidence checked | Important limitation |
|---|---|---|---|
| Narwhal API | Payroll in the 91 covered countries, when FX, economics or MCP share the same key. | Official government sources. Lookups by year, by date and for the next holiday, with a scope, local name and subdivision codes. Every account gets $10 of free credit a month, with commercial app use. | Far fewer countries than the large vendors. The responses read carry no observed-date field, and business days are counted in your own code. |
| Calendarific | A cheap monthly start with regional detail and holiday types across a very wide country list. | 230+ countries and 3,300+ regions, with ISO 3166-2 location filters on all plans. Starter costs $12 a month or $100 a year for 10,000 calls. | No observed-date field or business-day helper is documented. Free is 500 calls with attribution, and Free and Starter data update quarterly. |
| HolidayAPI | Multi-country payroll that needs observed dates, workday math and the right to keep results. | 250 countries, observed dates, /workday and /workdays endpoints, and years 1 to 2050+. Countries is $249 a year for 1,000,000 monthly requests, with commercial use and offline storage. | Billed yearly only. Regional holidays need the $399 States & Provinces plan, and the free plan's request limit is not published. |
| Nager.Date | Prototypes and internal tools where a free hosted API with no key and no stated rate limit is enough. | MIT code, 204 countries on the available-countries endpoint, six holiday types including Bank, and first-level regions. Our probe returned years 2025 to 2031. | The terms require active sponsorship for commercial use, with no price stated. Eid dates are left out, and some dates are flagged roughly or tentative. |
| Abstract API | Teams already on other Abstract APIs that want one holiday endpoint with regional entries. | 190+ countries and 3,500+ regions, years from 1 AD to past 2050. Free is 1,000 requests at one per second; Standard is $99 a month billed annually. | Commercial terms are not stated. The page says data is verified weekly in one place and monthly in another, and the docs list Russia as RE and the Bahamas as BH. |
| date-holidays | Node.js payroll engines that want holiday rules in process, with no quota and no network call. | 207 countries, ISO 3166-2 regions, five holiday types, a substitute-day flag and isHoliday(date). Version 3.38.0 was published on 24 October 2026. | You ship the updates. The data is CC BY-SA 3.0 with ShareAlike, and npm metadata lists a different licence string, so check the terms before you store derived data. |
| Federal Reserve Financial Services | Shifting US direct-deposit pay dates around days when the Reserve Banks are closed. | A FedCash schedule for 2026 to 2030 and a FedACH table with processing end and resume times. A Saturday holiday keeps Banks open the Friday before. | A web page, not an API, and it covers US dollar payment systems only. Copy the dates into your own table. |
Choose by requirement
A holiday falls on a weekend
Only two sources document the shifted day. HolidayAPI returns an observed date that differs from the date when a holiday lands on a weekend. date-holidays marks the replacing day with a substitute flag. Nager.Date, Calendarific and Abstract document no such field, and the Narwhal responses we read carry none. Whether staff are paid on the Friday before or the Monday after is your policy, so keep that rule in a table next to the holiday list.
Regional holidays
Calendarific accepts ISO 3166-2 codes such as us-ny or de-by on all plans. HolidayAPI needs the $399 yearly States & Provinces plan for the same. Nager.Date stops at the first level, so it shows Epiphany for DE-BW, DE-BY and DE-ST but nothing finer than a state. date-holidays follows ISO 3166-2. Narwhal entries carry subdivision codes, but check the coverage field of each country before relying on regions.
Bank, public and observance days
Payroll usually pays out on public holidays and ignores observances, so the type field matters. Nager.Date has six types, including Bank, School and Optional. date-holidays has five. Calendarific has four categories and a type filter on all plans. HolidayAPI sets public to true or false. Abstract uses free text. Narwhal marks each entry with a scope, such as federal government or national public.
How many years ahead
Leave accrual and shift planning need next year's calendar early. HolidayAPI and Abstract both reach 2050 and beyond. Our probe of Nager.Date returned 2025 to 2031 and an error outside that window. Calendarific says past and future years are supported without a number. date-holidays calculates from rules, with no fixed range. Narwhal takes the year in the path, so test the years you need for each country first.
Storing results
Paid HolidayAPI plans allow offline storage while you subscribe; Free limits it to 24 hours. Nager.Date's terms bar running your own holiday portal and ask commercial users to sponsor. Calendarific states no restriction and requires attribution on Free. date-holidays data is CC BY-SA 3.0. Abstract is silent. Narwhal includes commercial app use on every account; read its pricing and terms page for storage before you cache.
When the credit or quota runs out
Narwhal returns 402 insufficient_credits, charges no overage, and does not count errors; free credit refills on the first of the month. Calendarific counts every request, errors included, and answers 429 rate_limit_exceeded. Abstract Free returns 422 once credits are gone. HolidayAPI paid plans reset on the first at 00:00 UTC. Fetching one year per country once costs 37 calls across all Narwhal countries, about $0.07.
Cost per 1,000 calls
Plan price divided by included calls, times 1,000. Narwhal Calendars is priced per call at $2 per 1,000, with no plan to divide. Calendarific Starter is $12 / 10,000 = $1.20 monthly, or about $0.83 on the $100 yearly plan. HolidayAPI Countries is $249 / 12 months / 1,000,000, about $0.02. Abstract Standard as printed, $99 a month for 60,000 requests a year, is $1,188 / 60,000 = $19.80. Confirm that unit.
Is-holiday and business-day helpers
HolidayAPI offers /workday, which returns the date N working days after a start, and /workdays, which counts working days between two dates. Nager.Date has a next-holiday call and an is-today check. date-holidays has isHoliday(date). Calendarific and Abstract have none. Narwhal has a date lookup and a next-holiday call, and counts business days in your code, as its settlement how-to shows. It is also the only one here where we found MCP: 80 tools on one key.
Islamic and moving holidays
Eid dates depend on moon sighting. Nager.Date leaves Eid al-Fitr and Eid al-Adha out of its project and flags Hijri-based dates as roughly dated, which may shift one or two days. For staff in those countries, use a source that follows the government announcement. Narwhal reads official government sources, and its MCP tools include Hijri date conversion. Check each country you pay before you promise a date to staff.
Pay dates and bank closures
A public holiday list does not say when the bank moves your file. For US direct deposit, the Federal Reserve publishes a FedACH table with processing end and resume times. For a Saturday holiday the Reserve Banks stay open the Friday before; for a Sunday holiday they close the Monday after. Treat that table as a second input beside the holiday API, then count back from the pay date.
Each detailed provider page lists the first-party documentation used, its evidence boundaries, and its review date. Reviewed: