You're building an HR platform, a payroll system, or an EOR product. Your customers have employees in Germany, India, Brazil, and the Philippines. Each employee needs to see their local public holidays. Each payroll run needs to calculate working days correctly. Each leave request needs to check whether the requested day is already a holiday.

This sounds manageable until you actually try to implement it.

Germany alone has 16 Länder, each with different holidays. An employee in Munich (Bavaria) gets Assumption Day off; an employee in Berlin doesn't. Bavaria has 13 public holidays; Berlin has 9. Your holiday calendar isn't just "German holidays"—it's which state the employee works in.

India has 28 states, each with their own holiday calendars. The number of public holidays varies from roughly 10 to over 20 depending on the state. Some holidays are "restricted" (employees can choose to take them), others are "gazetted" (mandatory). Your simple "is this a holiday?" check just became a lookup into a complex matrix of jurisdictions and holiday types.

Brazil has national holidays plus state-level holidays plus municipal holidays. Is Black Consciousness Day a holiday? Depends on the state. Carnival? Depends on the municipality.

And then there's the question of religious holidays. Eid dates vary based on moon sighting—the actual observance can differ by a day or two from calculated predictions. Diwali is a public holiday in some Indian states but not others. Good Friday is a holiday in most of Europe but not everywhere.

This is what HR platforms actually deal with: not "holidays" as a simple list, but a sprawling, jurisdiction-dependent, annually-changing dataset that directly affects payroll accuracy and employee experience.

User reviews of major EOR platforms—Deel, Remote, Oyster, Papaya Global—consistently mention the same pain points around holidays:

"Absence of a global calendar for tracking local holidays."

"The system doesn't automatically incorporate local holidays for certain regions."

"Had to manually add holidays for our UK employees."

These aren't feature requests from demanding enterprise customers. They're basic expectations from any company with employees in multiple countries. If your HR platform can't tell an employee in Bavaria which days they have off, or can't correctly calculate working days for a Singapore payroll run, you've failed at a core function.

The stakes are real:

Payroll accuracy. If you're calculating prorated salary for a partial month, you need to know how many working days were in that month. Get the holidays wrong and you're either overpaying or underpaying employees. Both are problems.

Leave management. When an employee requests PTO for December 26th, your system should warn them that it's a public holiday in their jurisdiction (or not, depending on where they are). Letting employees "use" PTO on days they'd get off anyway is a bad experience.

Compliance. Some jurisdictions require premium pay for work on public holidays. Your system needs to know which days qualify. Getting this wrong isn't just an accounting issue—it's a compliance issue.

Employee experience. Your platform shows a calendar. Employees expect to see their local holidays on it. If a German employee in Bavaria sees Berlin's holidays, or an Indian employee in Karnataka sees Maharashtra's holidays, your product feels broken.

Most HR platforms handle holidays in one of a few ways, all with significant downsides:

Hardcoded lists. Someone wrote a JSON file with holiday dates three years ago. It covers the US, UK, and "Germany" (without regional breakdown). Adding a new country means someone manually researching and typing in dates. Nobody remembers to update it annually. When the UK added an extra bank holiday for the Queen's funeral, the file didn't know.

Customer-managed. "Just let customers configure their own holidays." This pushes the burden onto customers, who don't want to research statutory holidays for every jurisdiction where they have employees. They signed up for your platform to handle this complexity, not to do the data entry themselves.

Third-party API. Better, but most holiday APIs aren't built for HR use cases. They don't have regional granularity. They don't distinguish between public holidays and bank holidays. They don't handle the "observed date" logic when holidays fall on weekends. They give you raw data; the HR logic is still your problem.

Internal spreadsheets. Surprisingly common even at large companies. An operations person maintains an Excel file. It gets emailed around. Nobody's sure which version is current. Different teams use different copies that have drifted apart.

All of these approaches share a common failure mode: they work until they don't, and you discover they don't when an employee complains or a payroll calculation is wrong.

Let's be specific about the data requirements:

Not "Germany has holidays" but "Bavaria has these holidays, Berlin has these holidays, and they're different." Not "India has holidays" but "Karnataka observes Ugadi, Maharashtra observes Gudi Padwa, and they fall on the same date but have different names."

This regional granularity is non-negotiable for accurate HR operations. An employee's location determines their holiday entitlement, and location means state/province, not just country.

Is this a public holiday where businesses close? A bank holiday where banks close but other businesses might not? A "restricted" holiday where employees can choose whether to take it? An observance that's culturally significant but not a day off?

Different holiday types have different implications for leave calculations and payroll. A general-purpose "here's a list of holidays" API doesn't capture these distinctions.

Given an employee's jurisdiction, how many working days are in March? If their start date was March 15th, how many working days remain in the month for prorating their salary?

This calculation requires knowing both the weekend pattern (Monday-Friday in most places, but Sunday-Thursday in Israel, and Friday-Saturday was the weekend in UAE until 2022) and the holiday calendar for that specific jurisdiction.

Christmas falls on Saturday in some years. When that happens, is the observed holiday Friday or Monday? This varies by country and isn't always predictable—some governments announce it, others have standing rules, others do it inconsistently.

Your holiday API needs to provide not just "December 25 is Christmas" but "the observed date for Christmas 2027 is December 27" (or whatever the rule is for that jurisdiction).

We built World Data API with HR use cases in mind:

Holiday calendars for 230+ countries. Public holidays, bank holidays, and major observances. Updated annually and when governments announce changes.

Regional granularity. State/province-level holidays for countries where it matters: all 16 German Länder, Australian states, Canadian provinces, Indian states, Brazilian states. Not just "national holidays" but the actual holidays that apply to a specific location.

Working day calculations. Given a jurisdiction and date range, how many working days? Add N working days to a date. Subtract N working days. Check if a specific date is a working day. The arithmetic that payroll systems need, built in.

Holiday type classifications. We distinguish between public holidays, bank holidays, and observances. We note when holidays are "observed" on a different date than they technically fall.

We're a data API, not an HR system. There are things outside our scope:

Leave entitlement rules. We can tell you which days are public holidays in Germany. We can't tell you that German employees are entitled to 20 days of statutory leave plus public holidays, or how carryover works, or what happens to unused leave. That's labor law, not holiday data.

Premium pay rules. We can tell you which days are public holidays. We can't tell you whether employees working those days are entitled to 1.5x or 2x pay, or whether it varies by industry or collective bargaining agreement. That's compensation policy, not holiday data.

Company-specific holidays. If your customer gives employees their birthday off, or has a company-wide shutdown the week between Christmas and New Year, that's their policy. We provide statutory holidays; company holidays are your data to manage. You can't add custom holidays to API calculations.

Half-day holiday handling. Days like Christmas Eve that are half-days in some jurisdictions are treated as full holidays in our business day calculations. If you need half-day precision for payroll, you'll need to handle those specific cases in your application logic.

City-level holidays. We cover national and state/province level. Some countries (Brazil, Italy) have municipal holidays we don't track. If you have employees in cities with significant local holidays, verify coverage for those specific locations.

Religious holiday personalization. We can tell you when Eid al-Fitr is expected to fall based on astronomical calculations. We can't account for the fact that actual observance depends on moon sighting and may differ by a day or two. We can tell you Diwali's date; we can't tell you whether a specific employee observes it as a holiday.

We think it's important to be clear about these boundaries. Holiday data is foundational for HR systems, but it's not the whole story. Leave policies, pay rules, and company customs sit on top of the holiday data layer.

HR platforms can't afford to show employees wrong holiday information or calculate payroll incorrectly. Data quality matters.

We source holiday data from official government publications—gazettes, labor ministry announcements, legislative records. When governments announce changes (new holidays, date shifts, one-time additions like coronation holidays), we update promptly.

We're not scraping Wikipedia or relying on community contributions. We maintain the data ourselves and stand behind its accuracy.

That said, we're not perfect. Edge cases exist:

• Municipal holidays in some countries (Brazil, Italy) where we only cover national and state level

• Newly announced holidays that haven't propagated to our database yet

• Religious holidays where calculated dates and observed dates may differ

If you're operating in a jurisdiction where you need absolute certainty, verify our data against official sources. We're confident in our coverage, but we'd rather you validate than trust blindly.

You're building an HR platform, a payroll system, an EOR product, a time-off management tool, or any software that needs to know "is this day a holiday for this employee?"

You've been maintaining holiday spreadsheets and you're tired of the manual updates. Or you've tried a general-purpose holiday API and found it doesn't have the regional granularity you need. Or you're building something new and want to get holidays right from the start.

You understand that "holidays" isn't a simple problem when you're operating globally, and you need a data source that understands the complexity.

The API is REST-based, returns JSON, and authenticates via the X-API-Key header.

Holiday data (including regional holidays) is available on the free tier—60 requests per day, enough for development and light usage. Working day calculations are a premium endpoint requiring a paid tier.

Paid tiers: Starter at $9/month (15,000 requests), Pro at $49/month (100,000 requests), Growth at $149/month (500,000 requests). Annual billing saves about 25%.

Sign up at worlddataapi.com/dashboard to get an API key. Documentation is at worlddataapi.com/docs. We have guides for common HR use cases:

• Calculating Business Days in JavaScript

• Calculating Business Days in Python

• Handling Islamic Holidays

• International Holiday Support