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. Narwhal API is owned and operated by Nusantara Ventures, LLC.
Narwhal API
Payroll in the 37 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 37 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. Free is 5,000 calls a month and includes 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 Free includes commercial app use; read its pricing and terms page for storage before you cache.
When the monthly quota runs out
Narwhal returns 429 quota_exhausted, charges no overage, and does not count errors; quotas reset at 00:00 UTC on the first. 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, far under 5,000.
Cost per 1,000 calls
Plan price divided by included calls, times 1,000. Narwhal Basic is $59 / 100,000 = $0.59, and Pro is $149 / 1,000,000 = $0.149. 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: