How to Calculate Business Days in JavaScript

javascript

// Add 10 business days to a date, excluding US holidays
const response = await fetch(
	"https://worlddataapi.com/v1/business-days/US/add?start=2026-01-15&days=10",
	{ headers: { "X-API-Key": "YOUR_API_KEY" } },
);
const data = await response.json();
console.log(data.result); // "2026-01-29"

Or with curl:

bash

curl -X GET "https://worlddataapi.com/v1/business-days/US/add?start=2026-01-15&days=10" \
  -H "X-API-Key: YOUR_API_KEY"

That's the complete solution. If you need business day calculations that account for real holidays and regional variations, an API handles the complexity. The rest of this guide explains why the naive approach fails and when you might still want it.

Note: Business day calculations require a paid World Data API plan (Starter tier or above).

The Challenge#

Calculating business days sounds straightforward until you encounter the real world. Weekends vary by country (Israel uses Sunday-Thursday, UAE uses Monday-Friday). Holidays change every year. Regional holidays differ within the same country. Islamic and Chinese holidays follow lunar calendars that shift annually. Most date libraries ignore these realities, leaving you with calculations that silently produce wrong results.

Prerequisites#

Node.js 18+ or a modern browser with fetch support
A World Data API key (sign up for free, then upgrade to Starter or above for business day endpoints)
Basic familiarity with async/await in JavaScript

The Naive Approach#

The obvious solution: skip Saturdays and Sundays.

javascript

function addBusinessDays(startDate, days) {
	const result = new Date(startDate);
	let added = 0;

	while (added < days) {
		result.setDate(result.getDate() + 1);
		const dayOfWeek = result.getDay();
		if (dayOfWeek !== 0 && dayOfWeek !== 6) {
			added++;
		}
	}

	return result;
}

// Add 10 business days
const future = addBusinessDays(new Date("2026-01-15"), 10);
console.log(future.toISOString().split("T")[0]); // "2026-01-29"

This works for basic cases. It fails in production.

Why the Naive Approach Breaks#

Problem 1: Holidays#

The naive approach treats Christmas, New Year's Day, and Thanksgiving as business days. If you're calculating a payment due date or delivery estimate, this produces incorrect results.

javascript

// January 1, 2026 is New Year's Day (a holiday)
// The naive approach counts it as a business day
const result = addBusinessDays(new Date("2025-12-31"), 1);
console.log(result.toISOString().split("T")[0]); // "2026-01-01" — wrong

The actual next business day is January 2nd.

Problem 2: Regional Holidays#

California observes César Chávez Day (March 31). Texas doesn't. A "10 business days" calculation in California differs from the same calculation in Texas.

Problem 3: Non-Western Workweeks#

Israel's workweek runs Sunday through Thursday. The UAE recently shifted to Monday through Friday, but many Middle Eastern countries still use Sunday through Thursday. Your Saturday/Sunday check is wrong for a quarter of the world.

javascript

// January 3, 2026 is a Friday — a workday in most countries
// But it's a weekend day in Israel (workweek is Sun-Thu)

Problem 4: Moving Holidays#

Easter changes dates every year. Islamic holidays shift by approximately 11 days annually. Chinese New Year falls between January 21 and February 20 depending on the lunar calendar. Hardcoding holiday dates guarantees eventual failure.

Building a Holiday-Aware Solution#

You have two options: maintain holiday data yourself, or use an API.

Option 1: Maintain Your Own Holiday Data#

You'll need:

A holiday database covering every country and region you support
Logic for fixed holidays (July 4th)
Logic for relative holidays (4th Thursday of November)
Logic for observed holidays (when July 4th falls on Saturday, it's observed Friday)
Annual updates when governments change holiday schedules
Lunar calendar calculations for Islamic and Chinese holidays

This is feasible if you only support one country and can commit to annual maintenance.

Option 2: Use an API#

World Data API handles business day calculations directly:

javascript

async function addBusinessDays(location, startDate, days) {
	const params = new URLSearchParams({
		start: startDate,
		days: days.toString(),
	});

	const response = await fetch(
		`https://worlddataapi.com/v1/business-days/${location}/add?${params}`,
		{
			headers: {
				"X-API-Key": process.env.WORLD_DATA_API_KEY,
			},
		},
	);

	if (!response.ok) {
		throw new Error(`API error: ${response.status}`);
	}

	return response.json();
}

// Add 10 business days in the US
const result = await addBusinessDays("US", "2026-01-15", 10);
console.log(result);
// {
//   "location": "US",
//   "start": "2026-01-15",
//   "days": 10,
//   "type": "business",
//   "result": "2026-01-29",
//   "workweek": ["monday", "tuesday", "wednesday", "thursday", "friday"]
// }

Common Operations#

Check If a Date Is a Business Day#

javascript

async function isBusinessDay(location, date) {
	const response = await fetch(
		`https://worlddataapi.com/v1/business-days/${location}?date=${date}`,
		{
			headers: {
				"X-API-Key": process.env.WORLD_DATA_API_KEY,
			},
		},
	);

	const data = await response.json();
	return data.is_business_day;
}

// Is January 1, 2026 a business day in the US?
const isOpen = await isBusinessDay("US", "2026-01-01");
console.log(isOpen); // false (New Year's Day)

The response includes why it's not a business day:

json

{
	"location": "US",
	"date": "2026-01-01",
	"is_business_day": false,
	"reason": "holiday",
	"holiday": {
		"date": "2026-01-01",
		"name": "New Year's Day",
		"types": ["public"]
	},
	"next_business_day": "2026-01-02",
	"prev_business_day": "2025-12-31"
}

Count Business Days Between Two Dates#

javascript

async function countBusinessDays(location, startDate, endDate) {
	const params = new URLSearchParams({
		start: startDate,
		end: endDate,
	});

	const response = await fetch(
		`https://worlddataapi.com/v1/business-days/${location}/count?${params}`,
		{
			headers: {
				"X-API-Key": process.env.WORLD_DATA_API_KEY,
			},
		},
	);

	return response.json();
}

// How many business days in January 2026 (California)?
const result = await countBusinessDays("US-CA", "2026-01-01", "2026-01-31");
console.log(result);
// {
//   "location": "US-CA",
//   "start": "2026-01-01",
//   "end": "2026-01-31",
//   "type": "business",
//   "total_days": 31,
//   "business_days": 21,
//   "weekend_days": 8,
//   "holidays": 2,
//   "holiday_list": [
//     { "date": "2026-01-01", "name": "New Year's Day", "types": ["public"] },
//     { "date": "2026-01-19", "name": "Martin Luther King Jr. Day", "types": ["public"] }
//   ],
//   "workweek": ["monday", "tuesday", "wednesday", "thursday", "friday"]
// }

Subtract Business Days#

javascript

async function subtractBusinessDays(location, startDate, days) {
	const params = new URLSearchParams({
		start: startDate,
		days: days.toString(),
	});

	const response = await fetch(
		`https://worlddataapi.com/v1/business-days/${location}/subtract?${params}`,
		{
			headers: {
				"X-API-Key": process.env.WORLD_DATA_API_KEY,
			},
		},
	);

	return response.json();
}

// What date was 5 business days before January 15, 2026 in Germany?
const result = await subtractBusinessDays("DE", "2026-01-15", 5);
console.log(result.result); // "2026-01-08"

Handling Different Industries#

Financial applications often need banking days (which exclude bank holidays beyond public holidays). Government contractors need government days.

javascript

// Banking days in the UK
const bankingResult = await fetch(
	"https://worlddataapi.com/v1/business-days/GB/add?start=2026-08-25&days=5&type=banking",
	{ headers: { "X-API-Key": process.env.WORLD_DATA_API_KEY } },
);
// Accounts for the August bank holiday

The type parameter accepts:

business (default) — weekends + public holidays
banking — weekends + public holidays + bank holidays
government — weekends + public holidays + government office closures

Regional Precision#

Country-level queries use national holidays. Regional queries add state/province holidays:

javascript

// California includes César Chávez Day (March 31)
const caResult = await countBusinessDays("US-CA", "2026-03-01", "2026-03-31");

// Texas doesn't observe it
const txResult = await countBusinessDays("US-TX", "2026-03-01", "2026-03-31");

// California: 21 business days
// Texas: 22 business days

Use ISO 3166-2 codes for regional queries: US-CA, DE-BY (Bavaria), GB-SCT (Scotland).

Error Handling#

javascript

async function safeAddBusinessDays(location, startDate, days) {
	try {
		const response = await fetch(
			`https://worlddataapi.com/v1/business-days/${location}/add?start=${startDate}&days=${days}`,
			{
				headers: {
					"X-API-Key": process.env.WORLD_DATA_API_KEY,
				},
			},
		);

		if (!response.ok) {
			if (response.status === 400) {
				throw new Error("Invalid date format or location code");
			}
			if (response.status === 401) {
				throw new Error("Invalid API key");
			}
			if (response.status === 429) {
				throw new Error("Rate limit exceeded");
			}
			throw new Error(`API error: ${response.status}`);
		}

		return await response.json();
	} catch (error) {
		if (error instanceof TypeError) {
			throw new Error("Network error — check your connection");
		}
		throw error;
	}
}

Caching Strategy#

Holiday data doesn't change often. Cache aggressively:

javascript

const cache = new Map();

async function getCachedBusinessDayCheck(location, date) {
	const key = `${location}:${date}`;

	if (cache.has(key)) {
		return cache.get(key);
	}

	const result = await isBusinessDay(location, date);
	cache.set(key, result);

	// Holiday data is stable — cache for 24 hours
	setTimeout(() => cache.delete(key), 24 * 60 * 60 * 1000);

	return result;
}

For high-volume applications, consider fetching the holiday list once and performing calculations locally:

javascript

async function getHolidays(location, year) {
	const response = await fetch(
		`https://worlddataapi.com/v1/holidays/${location}?year=${year}`,
		{
			headers: {
				"X-API-Key": process.env.WORLD_DATA_API_KEY,
			},
		},
	);

	const data = await response.json();
	return new Set(data.holidays.map((h) => h.date));
}

// Cache the holiday set and check locally
const usHolidays2026 = await getHolidays("US", 2026);

function isHoliday(date) {
	return usHolidays2026.has(date);
}

When to Use the Naive Approach#

The naive Saturday/Sunday check is sufficient when:

You only operate in one country with no regional variations
Missing holidays is acceptable (internal estimates, not contractual deadlines)
You can manually handle edge cases (December has Christmas, etc.)

Use an API when:

Dates have legal or financial significance (payment terms, SLAs)
You support multiple countries or regions
You can't afford the maintenance burden of holiday data

Common Pitfalls#

Assuming Monday-Friday everywhere. Israel, UAE, and other countries have different workweeks. Always use the API's workweek data rather than hardcoding weekend days.

Ignoring regional holidays. A calculation using US misses California's Cesar Chavez Day or Texas's state holidays. Use ISO 3166-2 codes (US-CA, US-TX) when regional precision matters.

Not handling the response's next/previous business day. When checking if a date is a business day, the API returns next_business_day and prev_business_day. Use these instead of manually incrementing dates.

Caching without considering year boundaries. Holiday data is year-specific. If you cache the 2026 holiday list, queries for January 2027 will use stale data.

Forgetting timezone implications. A date string like "2026-01-15" is interpreted in the location's local timezone. If your server is in UTC but the location is US-Pacific, ensure you're passing the correct local date.

Limitations#

World Data API calculates Islamic holidays astronomically. Actual observance in some countries depends on physical moon sighting and may differ by 1-2 days. For contracts governed by Islamic calendar dates, verify with local authorities.

Half-day holidays (Christmas Eve in some countries) are treated as full holidays in business day calculations.

Summary#

Business day calculations require more than skipping weekends. Holidays, regional variations, and non-Western workweeks make the naive approach unreliable for production use. The World Data API business days endpoints handle these complexities, supporting 230+ countries with regional precision, banking and government day types, and automatic handling of moving holidays.

For applications where dates have legal, financial, or customer-facing significance, using an API eliminates the maintenance burden of holiday data and the risk of silent calculation errors.

Ready to add accurate business day calculations to your application? Get your API key and start with the free tier, then upgrade to Starter ($9/month) for business day endpoints.

Related guides:

Working with ISO Country and Region Codes — Understanding location codes
Calculating Delivery Dates with Holiday Awareness — E-commerce applications
Caching Strategies for Reference Data APIs — Optimizing API usage