// Get Islamic holidays for Saudi Arabia in 2026
const response = await fetch(
	"https://worlddataapi.com/v1/holidays/SA?year=2026",
	{ headers: { "X-API-Key": "YOUR_API_KEY" } },
);
const data = await response.json();

// Find Eid al-Fitr
const eid = data.holidays.find((h) => h.name.includes("Eid al-Fitr"));
console.log(eid);
// { "date": "2026-03-20", "name": "Eid al-Fitr", "types": ["public"] }

# Get Islamic holidays for Saudi Arabia in 2026
import requests

response = requests.get(
    "https://worlddataapi.com/v1/holidays/SA?year=2026",
    headers={"X-API-Key": "YOUR_API_KEY"}
)
data = response.json()

# Find Eid al-Fitr
eid = next((h for h in data["holidays"] if "Eid al-Fitr" in h["name"]), None)
print(eid)
# {"date": "2026-03-20", "name": "Eid al-Fitr", "types": ["public"]}

# Get Islamic holidays for Saudi Arabia in 2026
curl -X GET "https://worlddataapi.com/v1/holidays/SA?year=2026" \
  -H "X-API-Key: YOUR_API_KEY"

Important: Islamic holiday dates provided by World Data API are based on astronomical calculations. Actual observance dates may vary by 1-2 days in countries that rely on physical moon sighting rather than calculated calendars.

Islamic holidays present unique challenges for software. Unlike Christmas (always December 25) or Thanksgiving (4th Thursday of November), Islamic holiday dates are fundamentally uncertain until days before they occur. This guide explains why and how to handle it.

Building software that handles Islamic holidays requires dealing with three interrelated problems:

1. Unpredictable dates - Islamic months begin when the crescent moon is sighted, not on a fixed calendar date. This means Eid al-Fitr might fall on different days in different countries, even though it marks the same religious occasion.

2. 11-day annual drift - The Islamic calendar is approximately 11 days shorter than the Gregorian calendar, so holidays shift earlier each year. You cannot hardcode "Ramadan usually falls in spring" because it cycles through all seasons over a 33-year period.

3. Regional variation - Saudi Arabia might announce Eid on Saturday while Pakistan observes it on Sunday based on local moon sighting. A global application needs country-specific handling, not a single "Islamic holidays" list.

For payment systems, HR platforms, and scheduling applications, this uncertainty creates real business problems: you cannot guarantee "no transactions on Eid" or block vacation requests for "Eid week" when you do not know the exact dates until 1-3 days beforehand.

The Islamic calendar (Hijri) is purely lunar — 12 months of 29 or 30 days, totaling 354 or 355 days per year. This means:

1. Islamic dates shift approximately 11 days earlier each Gregorian year. Ramadan 2026 falls in late February/March. By 2030, it'll be in January. By 2035, it'll be in November.

2. The same Islamic date falls on different Gregorian dates in different years. There's no "Eid is always around this time" pattern to rely on.

3. Month start dates depend on moon sighting. A new Islamic month begins when the crescent moon is physically observed after sunset. Clouds, atmospheric conditions, or local authority decisions can shift the date.

Two methods determine Islamic dates:

Mathematical models predict when the new moon should be visible. This gives consistent, predictable dates years in advance. Saudi Arabia's Umm al-Qura calendar uses this approach for civil purposes.

Traditional practice requires human observation of the crescent moon. Different countries and religious authorities may see the moon on different nights, causing Eid to fall on different days in different locations.

The practical result: Morocco might celebrate Eid al-Fitr on Saturday while Indonesia celebrates on Sunday.

A payment system promising "no charges on Eid" cannot know the exact Eid date until 1-3 days beforehand in moon-sighting countries. An HR system blocking vacation requests for "Eid week" faces the same problem.

Pakistan and Saudi Arabia may observe Eid on different days. A multinational payroll system needs country-specific dates, not a single "Islamic holidays" list.

APIs (including World Data API) provide calculated dates based on astronomical models. These match many countries' official calendars but may differ from moon-sighted dates by 1-2 days.

Before implementing Islamic holiday handling, you need:

• World Data API key - Sign up at worlddataapi.com for free (60 requests/day) or paid tier for production use

• Basic understanding of REST APIs - Familiarity with making HTTP requests and parsing JSON responses

• Date handling fundamentals - Understanding of ISO 8601 date formats and timezone considerations

For the code examples in this guide, you should have:

• JavaScript: Node.js 18+ or modern browser environment with fetch support

• Python: Python 3.8+ with the requests library installed (pip install requests)

For most applications, calculated dates are sufficient:

async function getIslamicHolidays(country, year) {
	const response = await fetch(
		`https://worlddataapi.com/v1/holidays/${country}?year=${year}`,
		{ headers: { "X-API-Key": API_KEY } },
	);
	const data = await response.json();

	// Filter to Islamic holidays
	const islamicHolidays = data.holidays.filter(
		(h) =>
			h.name.includes("Eid") ||
			h.name.includes("Ramadan") ||
			h.name.includes("Mawlid") ||
			h.name.includes("Isra") ||
			h.name.includes("Ashura"),
	);

	return islamicHolidays;
}

Display with appropriate context:

function IslamicHolidayNotice({ holiday }) {
	return (
		<div className="holiday-notice">
			<strong>{holiday.name}</strong>
			<time>{formatDate(holiday.date)}</time>
			<small>
				Date based on astronomical calculation. Actual observance may
				vary by 1-2 days depending on moon sighting.
			</small>
		</div>
	);
}

For business-critical applications, account for date uncertainty:

function getEidWindow(calculatedDate) {
	const date = new Date(calculatedDate);

	// Eid could fall 1 day before or after the calculated date
	const earliest = new Date(date);
	earliest.setDate(date.getDate() - 1);

	const latest = new Date(date);
	latest.setDate(date.getDate() + 1);

	return {
		earliest: earliest.toISOString().split("T")[0],
		calculated: calculatedDate,
		latest: latest.toISOString().split("T")[0],
	};
}

const eidWindow = getEidWindow("2026-03-20");
// {
//   earliest: "2026-03-19",
//   calculated: "2026-03-20",
//   latest: "2026-03-21"
// }

For scheduling systems:

function scheduleAroundEid(task, eidDate) {
	const window = getEidWindow(eidDate);

	// Don't schedule anything in the uncertainty window
	if (task.date >= window.earliest && task.date <= window.latest) {
		return {
			scheduled: false,
			reason: "Date falls within Eid uncertainty window",
			suggestedDate: addBusinessDays(window.latest, 1),
		};
	}

	return { scheduled: true };
}

For applications requiring confirmed dates, monitor official announcements:

const COUNTRY_AUTHORITIES = {
	SA: "Saudi Supreme Court",
	AE: "UAE Moon Sighting Committee",
	PK: "Central Ruet-e-Hilal Committee",
	ID: "Indonesian Ministry of Religious Affairs",
	MY: "Malaysian Islamic Authority",
};

function getAuthorityNote(countryCode) {
	const authority = COUNTRY_AUTHORITIES[countryCode];
	if (authority) {
		return `Final date confirmed by ${authority}. Check official announcements.`;
	}
	return "Date based on astronomical calculation.";
}

The month of fasting. Business hours often change, productivity may shift, and some countries reduce work hours.

// Ramadan spans approximately 29-30 days
// The API returns the start date
const ramadanStart = holidays.find((h) => h.name.includes("Ramadan"));

Marks the end of Ramadan. Typically 1-3 days of public holiday depending on country.

// Some countries observe multiple days
const eidDays = holidays.filter((h) => h.name.includes("Eid al-Fitr"));
// May return multiple entries for multi-day observance

The Festival of Sacrifice, occurring approximately 70 days after Eid al-Fitr. Often 3-4 days of public holiday.

• Mawlid (Prophet's Birthday) — Some countries observe, others don't

• Isra and Mi'raj — Night Journey commemoration

• Ashura — Particularly significant in Shia Islam

async function isIslamicHolidayWindow(country, date) {
	const year = new Date(date).getFullYear();
	const holidays = await getIslamicHolidays(country, year);

	for (const holiday of holidays) {
		const window = getEidWindow(holiday.date);
		if (date >= window.earliest && date <= window.latest) {
			return {
				inWindow: true,
				holiday: holiday.name,
				note: "Date falls within holiday uncertainty window",
			};
		}
	}

	return { inWindow: false };
}

// Usage in payment scheduling
async function schedulePayment(country, preferredDate) {
	const year = new Date(preferredDate).getFullYear();
	const holidays = await getIslamicHolidays(country, year);

	for (const holiday of holidays) {
		const window = getEidWindow(holiday.date);
		if (
			preferredDate >= window.earliest &&
			preferredDate <= window.latest
		) {
			// Schedule after the uncertainty window
			return {
				scheduledDate: getNextBusinessDay(window.latest),
				warning: `Original date near ${holiday.name}. Rescheduled to avoid uncertainty.`,
			};
		}
	}

	return { scheduledDate: preferredDate };
}

function createLeavePolicy(country) {
	return {
		// Acknowledge that Islamic holiday dates are approximate
		islamicHolidayBuffer: 1, // days

		getBlockedDates: async (year) => {
			const holidays = await getIslamicHolidays(country, year);

			const blocked = [];
			for (const holiday of holidays) {
				const window = getEidWindow(holiday.date);
				blocked.push({
					start: window.earliest,
					end: window.latest,
					reason: `${holiday.name} (date may vary)`,
				});
			}
			return blocked;
		},
	};
}

Be transparent about date uncertainty:

function formatIslamicHoliday(holiday) {
	const date = new Date(holiday.date);

	return {
		name: holiday.name,
		expectedDate: formatDate(date),
		disclaimer: holiday.name.includes("Eid")
			? "Expected date. Actual date depends on moon sighting and may differ by 1-2 days."
			: "Expected date based on Islamic calendar calculations.",
	};
}

Islamic dates cycle through the Gregorian calendar approximately every 33 years. This has implications for long-term planning:

// Ramadan in various years (approximate start dates):
// 2026: March
// 2030: January
// 2035: November
// 2040: September
// 2045: July
// 2050: May
// 2055: March (back to similar timing as 2026)

For applications doing multi-year projections, don't assume Islamic holidays fall in any particular season.

World Data API provides Islamic holiday data for countries where they're officially observed:

// Countries with Islamic public holidays
const ISLAMIC_HOLIDAY_COUNTRIES = [
	"SA", // Saudi Arabia
	"AE", // UAE
	"PK", // Pakistan
	"ID", // Indonesia
	"MY", // Malaysia
	"EG", // Egypt
	"TR", // Turkey
	"BD", // Bangladesh
	"IR", // Iran
	"IQ", // Iraq
	"JO", // Jordan
	"KW", // Kuwait
	"BH", // Bahrain
	"QA", // Qatar
	"OM", // Oman
	"MA", // Morocco
	"DZ", // Algeria
	"TN", // Tunisia
	// ... and many more
];

World Data API uses astronomical calculations. Countries using physical moon sighting may observe holidays 1-2 days from the calculated date. For applications where exact dates are critical, verify with local religious or government authorities.

Within some countries, different communities may observe different dates. The API provides the official government-recognized date.

Some holidays (particularly Ashura) have different significance in Sunni and Shia traditions. The API provides dates without distinguishing between traditions.

The most common mistake is displaying API-provided dates without any disclaimer. Users in moon-sighting countries will notice when the actual holiday differs from what your app showed.

Fix: Always include context that dates are calculated and may vary by 1-2 days.

Eid al-Fitr in Saudi Arabia and Pakistan may fall on different days. Using a single "Eid date" for multinational applications will be wrong for some users.

Fix: Query holiday data per country and handle each market independently.

Assuming Ramadan falls in a particular month or season will fail within a few years as the Islamic calendar drifts approximately 11 days earlier annually.

Fix: Query holiday data dynamically each year rather than assuming seasonal patterns.

Eid al-Adha can be 3-4 days in some countries. Checking only a single date will miss extended closures.

Fix: Filter for all entries containing the holiday name, as the API may return multiple days.

Ramadan 2026 starts in late February. If you only query year 2026, you might miss holidays that span year boundaries or occur in late December/early January.

Fix: Query adjacent years when calculating around year boundaries.

Islamic holidays require different handling than fixed-date holidays due to three factors: lunar calendar drift (approximately 11 days per year), moon-sighting uncertainty (1-2 day variation), and regional differences (different countries may observe on different days).

Key takeaways:

• Use calculated dates from the API but always communicate that actual dates may vary

• Build in flexibility with date windows for business-critical applications

• Query data per country rather than using global dates

• Monitor official announcements for time-sensitive applications

World Data API provides calculated Islamic holiday dates for 230+ countries based on astronomical models. These dates match official civil calendars in most countries but may differ from moon-sighted observances.

Ready to handle Islamic holidays in your application? Sign up for free and start with 60 API requests per day, or upgrade to a paid plan for production use.

• Adding International Holiday Support to Your App — Broader integration patterns

• How to Calculate Business Days in JavaScript — Working days with holidays

• Building a Holiday Calendar Component in React — UI implementation