API des jours fériés.

Présentation

Le Maroc dispose d'un calendrier de jours fériés à trois dimensions : des fêtes nationales à dates fixes dans le calendrier grégorien, des fêtes religieuses dont la date dépend de l'observation de la lune, et des jours exceptionnels décidés par les autorités à court terme.

Cette nature hybride rend toute liste statique obsolète dès la première fête islamique de l'année. L'API des jours fériés de Calendar API centralise ce référentiel, le maintient à jour, et expose un statut explicite pour chaque événement.

Types de jours fériés

• National — Fêtes civiles à date fixe : Fête du Trône (30 juillet), Fête de l'Indépendance (18 novembre), Nouvel An Amazigh (14 janvier)…
• Religious — Fêtes islamiques : Aid Al Fitr, Aid Al Adha, Awal Muharram, Mawlid… Dates calculées astronomiquement puis confirmées par observation lunaire.
• Exceptional — Jours fériés ponctuels décrétés par le gouvernement ou ponts accordés.

Fêtes religieuses Maroc : statut Estimé et Officiel

• Official — Date confirmée, fiable pour l'exécution de traitements.
• Estimated — Date calculée, susceptible de décalage d'un jour. Utilisez un polling horaire pour détecter le changement de statut.

Installation

pip install pycalendar-api

Instanciez le client avec votre clé API obtenue depuis la console d'administration.

from pycalendar_api import CalendarApi

# Directement
api = CalendarApi('YOUR_API_KEY')

# Ou via variable d'environnement CALENDAR_API_KEY
api = CalendarApi.from_env()

# Vérifier la disponibilité
print(api.health())
# ApiHealth(api_status='UP', appname='calendar-api', ...)

Vérifier si une date est un jour férié

L'opération la plus courante : un check unitaire qui retourne un objet HolidayCheckResult avec l'ensemble des métadonnées si la date est fériée.

from pycalendar_api import CalendarApi, to_date

api = CalendarApi.from_env()

result = api.holidays.is_holiday(to_date('14/01/2025'))
print(result)
# HolidayCheckResult(
#     date=datetime.date(2025, 1, 14),
#     is_holiday=True,
#     description='Nouvel An Amazigh',
#     holiday_type=<CalHolidayType.NATIONAL: 'National'>,
#     status=<CalHolidayStatus.OFFICIAL: 'Official'>,
#     country_code='MA'
# )

# Jour ouvrable normal
result2 = api.holidays.is_holiday(to_date('15/01/2025'))
# HolidayCheckResult(date=..., is_holiday=False, description=None, ...)

Lister les jours fériés d'une année

Retourne la liste ordonnée de tous les jours fériés d'une année, incluant type et statut pour chaque entrée.

from pycalendar_api import CalendarApi

api = CalendarApi.from_env()

holidays = api.holidays.year(2025)
# [Holiday(...), Holiday(...), ...]

# Filtrer par type
religious = [h for h in holidays if h.holiday_type == 'Religious']
national   = [h for h in holidays if h.holiday_type == 'National']

# Intégration Polars
import polars as pl
df = pl.DataFrame([
    {'date': h.date, 'description': h.description,
     'type': h.holiday_type, 'status': h.status}
    for h in holidays
])

Lister plusieurs années

Utile pour initialiser un référentiel historique ou retraiter des séries chronologiques longues.

holidays_2017_2026 = api.holidays.years(list(range(2017, 2027)))
# Liste complète des fériés sur 10 ans
# Données disponibles depuis 2006 (fêtes religieuses qualifiées)

Pattern polling pour les fêtes religieuses

Pour les systèmes de production qui ne peuvent pas tolérer un décalage d'un jour sur une fête islamique, implémentez un polling qui surveille le passage de Estimated à Official.

import time
from pycalendar_api import CalendarApi

api = CalendarApi.from_env()

def watch_estimated_holidays(year: int, interval_seconds: int = 3600):
    """Poll toutes les `interval_seconds` jusqu'à ce que toutes les
    fêtes religieuses de l'année soient Official."""
    while True:
        holidays = api.holidays.year(year)
        estimated = [
            h for h in holidays
            if h.holiday_type == 'Religious' and h.status == 'Estimated'
        ]
        if not estimated:
            print(f"Toutes les fêtes {year} sont officielles.")
            break
        print(f"{len(estimated)} fête(s) encore estimée(s), prochain check dans {interval_seconds}s")
        time.sleep(interval_seconds)

Modèles de réponse

Holiday

@dataclass
class Holiday:
    description:  str             # ex: "Aid Al Fitr"
    day:          int
    month:        int
    date:         date
    holiday_type: CalHolidayType  # National | Religious | Exceptional
    status:       CalHolidayStatus # Official | Estimated
    country_code: str             # "MA"

@dataclass
class HolidayCheckResult:
    date:         date
    is_holiday:   bool
    description:  str   # None si is_holiday=False
    holiday_type: CalHolidayType   # None si is_holiday=False
    status:       CalHolidayStatus  # None si is_holiday=False
    country_code: str