Holiday Categories

The framework offers multiple holiday categories to classify different types of observances, enabling users to filter holidays by official status, religious significance, or cultural importance.

Overview

Holiday categories enable you to filter holidays based on their nature and official recognition. Each country defines which categories it supports, and holidays are classified accordingly.

Category Types

Official Status Categories

PUBLIC

Official holidays recognized by the government that typically provide time off from work and school for the general population.

Examples:

New Year's Day in most countries
Independence Day in the United States
Christmas Day in Christian-majority countries

GOVERNMENT

Holidays observed by government institutions but may not provide general time off for all workers.

Examples:

Flag Day in some jurisdictions
Government-designated commemorative days

WORKDAY

Holidays that are officially recognized but do not provide time off from work. Often ceremonial or commemorative in nature.

Examples:

Constitution Day in some countries
Memorial days that are observed but not as public holidays

UNOFFICIAL

Commonly celebrated cultural holidays with no official government recognition or mandated time off. These are widely observed cultural celebrations, but exclude novelty, internet, or marketing "national days".

Examples:

Halloween
Saint Patrick's Day
Valentine's Day

Institutional Categories

BANK

Holidays specifically observed by banking institutions, which may differ from general public holidays.

Examples:

Additional bank-specific closures
Good Friday (in some countries)

SCHOOL

Holidays specific to educational institutions.

Examples:

Education-related observances
Teacher's Day

ARMED_FORCES

Holidays specific to military personnel and institutions.

Examples:

Armed Forces Day
Military commemoration days

Special Categories

OPTIONAL

Optional holidays that individuals or organizations may observe, often with flexible implementation.

Examples:

Cultural observances with optional recognition
Religious holidays for minority populations

MANDATORY (deprecated)

Holidays that were legally required to be observed in specific contexts. Previously used in Macau, where "Mandatory (Statutory) Holidays" have since been reclassified under the PUBLIC category, and "General Holidays" are now included in the OPTIONAL category, following the same approach as in Hong Kong.

HALF_DAY

Holidays observed for only part of a day, typically resulting in reduced working hours rather than a full day off.

Examples:

Christmas Eve (afternoon only)
New Year's Eve (afternoon only)

DE_FACTO

Holidays that are legally treated equivalently to public holidays for specific purposes (such as working day calculations) but are not officially designated as public holidays. These observances have legal backing that grants them similar status to public holidays in certain contexts.

Examples:

Sweden: Midsummer Eve (Midsommarafton), Christmas Eve (Julafton), and New Year's Eve (Nyårsafton) - per Semesterlag (SFS 1977:480), these are treated equivalently to Sundays and public holidays for working day calculations, though they are not official public holidays.
Switzerland: Easter Sunday (Ostersonntag), Whit Sunday (Pfingstsonntag), and Federal Day of Thanksgiving, Repentance, and Prayer (Eidgenössischer Bettag) - per Zürich's Ruhetags- und Ladenöffnungsgesetz vom 26. Juni 2000.

Usage:

import holidays
from holidays.constants import PUBLIC, DE_FACTO

# For accurate is_working_day() behavior in Sweden.
se = holidays.Sweden(categories=(PUBLIC, DE_FACTO), years=2024)
print(se.is_working_day('2024-12-24'))  # False (Christmas Eve)

Religious Categories

CATHOLIC

Holidays specific to the Catholic Christian tradition.

Examples:

Corpus Christi
Feast of the Immaculate Conception

PROTESTANT

Holidays specific to the Protestant Christian tradition.

Examples:

In Austria (1956-2018), Good Friday was treated as a public holiday for members of the Evangelical Churches of the Augsburg and Helvetic Confessions, the Methodist Church, and the Old Catholic Church (the special provision was removed via BGBl. I Nr. 22/2019).

CHRISTIAN

General Christian holidays observed by multiple denominations.

Examples:

Christmas Day
Easter Sunday

ORTHODOX

Holidays specific to the Orthodox Christian tradition.

Examples:

Orthodox Christmas
Orthodox Easter

ISLAMIC

Holidays specific to the Islamic tradition.

Examples:

Eid al-Adha
Eid al-Fitr

HINDU

Holidays specific to the Hindu tradition.

Examples:

Diwali
Holi

HEBREW

Holidays specific to the Jewish tradition.

Examples:

Passover
Yom Kippur

SABIAN

Holidays specific to the Sabian religious tradition.

Examples:

Used in Iraq for Sabian community holidays

YAZIDI

Holidays specific to the Yazidi religious tradition.

Examples:

Used in Iraq for Yazidi community holidays

Ethnic and Cultural Categories

ARMENIAN

Holidays specific to Armenian culture and traditions.

Examples:

Used in Argentina for Armenian community holidays

ALBANIAN

Holidays specific to Albanian culture and traditions.

Examples:

Used in North Macedonia for Albanian community holidays

BOSNIAN

Holidays specific to Bosnian culture and traditions.

Examples:

Used in North Macedonia for Bosnian community holidays

SERBIAN

Holidays specific to Serbian culture and traditions.

Examples:

Used in North Macedonia for Serbian community holidays

TURKISH

Holidays specific to Turkish culture and traditions.

Examples:

Used in North Macedonia for Turkish community holidays

ROMA

Holidays specific to Roma culture and traditions.

Examples:

Used in North Macedonia for Roma community holidays

VLACH

Holidays specific to Vlach culture and traditions.

Examples:

Used in North Macedonia for Vlach community holidays

Usage Examples

Filtering by Single Category

Get only public holidays for the United States:

import holidays
from holidays.constants import PUBLIC

us_public = holidays.UnitedStates(categories=PUBLIC, years=2024)
print(f"US public holidays in 2024: {len(us_public)}")

Filtering by Multiple Categories

Get both public and bank holidays for Belgium:

import holidays
from holidays.constants import PUBLIC, BANK

belgium_holidays = holidays.Belgium(categories=(PUBLIC, BANK), years=2024)
for date, name in sorted(belgium_holidays.items()):
    print(f"{date}: {name}")

Religious Category Example

Get only Catholic holidays in Germany (Saxony subdivision):

import holidays
from holidays.constants import CATHOLIC

germany_catholic = holidays.Germany(subdiv='SN', categories=CATHOLIC, years=2024)
for date, name in sorted(germany_catholic.items()):
    print(f"{date}: {name}")

Unofficial Holidays Example

Get unofficial holidays in the United States:

import holidays
from holidays.constants import UNOFFICIAL

us_unofficial = holidays.UnitedStates(categories=UNOFFICIAL, years=2024)
for date, name in sorted(us_unofficial.items()):
    print(f"{date}: {name}")

Country-Specific Support

Not all countries support every category. Each country defines the categories it recognizes based on its legal and cultural framework.

Checking Supported Categories

Check which categories a country supports:

import holidays

print(f"US supported categories: {holidays.UnitedStates.supported_categories}")

print(f"Germany supported categories: {holidays.Germany.supported_categories}")

The returned categories are lowercase strings corresponding to the constants in holidays.constants.

Examples by Country

United States: ('government', 'half_day', 'public', 'unofficial')

Supports federal holidays, state holidays, and cultural observances

Germany: ('catholic', 'public', 'school')

Supports public holidays, Catholic holidays in certain regions, and school holidays

India: ('optional', 'public')

Supports national holidays and optional regional observances

Argentina: ('armenian', 'bank', 'government', 'hebrew', 'islamic', 'public')

Supports multiple religious traditions and institutional categories

Implementation Guidelines

When Defining New Countries

When adding support for a new country, consider:

Official Status: Which holidays are legally mandated public holidays?
Religious Diversity: What religious communities have recognized holidays?
Cultural Significance: Are there widely celebrated unofficial holidays?
Institutional Needs: Do banks, schools, or government have specific observances?

Category Selection Principles

PUBLIC: Holidays mandated by law with general time off
GOVERNMENT: Holidays observed by government institutions but may not provide general time off for all workers
WORKDAY: Recognized but are working holidays
UNOFFICIAL: Widely celebrated but not official
DE_FACTO: Legally recognized holidays that must be treated like public holidays for specific purposes (e.g., working day calculations) but lack official public holiday status
Religious categories: Use when holidays apply to particular religious communities
Institutional categories: Use when holidays apply to specific sectors

Default Behavior

When no categories are specified, all countries and markets default to returning PUBLIC holidays, as these are typically what users expect when asking for a country's holidays.

import holidays
from holidays.constants import PUBLIC

# These are equivalent for all countries and markets.
us_default = holidays.UnitedStates(years=2024)
us_public = holidays.UnitedStates(categories=PUBLIC, years=2024)

Contributing

When contributing new countries or updating existing ones:

Research the official holiday framework for the country
Identify which categories are appropriate
Classify each holiday according to its official status and cultural significance
Document the reasoning for category assignments
Provide examples in tests demonstrating category usage