API Calendrier Marocain | Jours Fériés & Ouvrables REST + SDK Python Holidays API
National holidays of any year and Religious holidays of past years
OpenAPI Specification
openapi: 3.2.0
info:
title: Calendar Holidays API
version: v1
summary: Calendar API for Moroccan Holidays and Open Business Days
description: '
## Try Calendar API
This interactive panel allows you to explore the whole API and to understand the different datastructures and parameters
used by every endpoint. You can also test every **active** APIKey you have.
## Setup your APIKey
Copy any **active** APIKey from your console and set it in the `Authentication` side panel.
That''s it :-), now you can explore any endpoint
## Holidays
This API allows to list, search and check if a `date` is a Moroccan holiday.
| Endpoint | Description |
| ------------------------ | :--------------------------------------------------------------------------------------------------------------------------------- |
| **/holidays/is-holiday** | Checks if a date is an `Official` Holiday |
| **/holidays/{year}** | List the holidays of the year. |
| **/holidays** | Lists all national Holidays. Since Morocco is a Kingdom, there are some Holidays that depend on the birthday of the current King. |
**N.B:**
Please note that if it''s a **future** `year`, the **religious holidays** are `Estimated` and not official because they depend on the moon sighting.
Once confirmed, the Holiday becomes `Official` and the adequate flag will be updated accordingly.
## Business Days (bdays)
This API calculates the `next` and `previous` **Open Business Day** of a date. You can also get the Open Days for a whole year or any month of a year
| Endpoint | Description |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| **/bdays/{year}** | Generate the Business days for the whole `year` |
| **/bdays/{year}/{month}** | Generate the Business days of a `month` of the `year` |
| **/bdays/next** | Calculate **the next** Open day relative to the provided `date` |
| **/bdays/previous** | Calculate **the previous** Open day relative to the provided `date` |
| **/bdays/count** | Count the business days between 2 dates (included) |
| **/bdays/between** | List the business days between 2 dates (included) |
| **/bdays/span/month** | Calculate the interval (Start/End date) of a `month`. i.e: Interval of the month 5 of year 2025 |
| **/bdays/span/quarter** | Calculate the interval (Start/End date) of a `quarter`. i.e: Interval of the Q2 of year 2024 |
| **/bdays/span/semester** | Calculate the interval (Start/End date) of a `semester`. i.e: Interval of the S1 of year 2026 |
| **/bdays/span/year** | Calculate the interval (Start/End date) of the `year`. i.e: Interval of the year 2021 |
## Data dictionary
### Holiday Type:
| Value | Description |
| --------------- | :--------------------------------------------------------------------------- |
| **National** | The date is a national Holiday |
| **Religious** | The date is a Religious Holiday (Check the status if it''s Confirmed or not) |
| **Exceptional** | The date is an exceptional Holiday |
### HolidayStatus (status)
| Value | Description |
| ------------- | :--------------------------------------------------------- |
| **Official** | The Holiday is Official |
| **Estimated** | Religious Holidays are estimated before the moon sighting |
'
contact:
name: UNRAVEL DESIGNS
url: https://unraveldesigns.ma
email: ud@unraveldesigns.ma
license:
name: Proprietary
servers:
- url: https://calendar-api.ma
description: Casablanca (production) — resolved from the relative server "/" published in the original spec at https://calendar-api.ma/schema/openapi.json
security:
- apiKey: []
- sessionCookie: []
tags:
- name: Holidays
description: National holidays of any year and Religious holidays of past years
x-tag-expanded: false
paths:
/api/v1/holidays:
get:
tags:
- Holidays
summary: List Holidays
operationId: ApiV1HolidaysHolidays
parameters:
- name: description
in: query
schema:
oneOf:
- type: string
- type: 'null'
type: string
minLength: 2
title: description
description: 'Case insensitive textual search. Supports wildcards. NB: Accents are respected'
examples:
- null
- trô
- Trava
- Amaz
description: 'Case insensitive textual search. Supports wildcards. NB: Accents are respected'
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
description-example-1:
summary: 'null: Disable this filter'
description-example-2:
summary: Search `Fête du trône`
value: trô
description-example-3:
summary: Search `Fête du travail`
value: Trava
description-example-4:
summary: Search `Nouvel An Amazigh`
value: Amaz
- name: holiday_type
in: query
schema:
$ref: '#/components/schemas/CalHolidayType'
description: 'There are Three Types of holidays:
- **Religious**: Include only Religious holidays. i.e: Eid el fitr, ...
- **National**: Include only National holidays. i.e: Fête du travail, Fête du trône, ...
- **Exceptional**: Include only Exceptional holidays.
- **ND::Null**: Disable this filter'
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
holiday_type-example-1:
summary: 'null: Disable this filter'
value: ND
- name: day
in: query
schema:
oneOf:
- type: integer
- type: 'null'
type: integer
maximum: 31
minimum: 1
title: day
description: Filter by the Day of the Holiday
examples:
- null
- 1
- 14
description: Filter by the Day of the Holiday
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
day-example-1:
summary: 'null: Disable this filter'
day-example-2:
summary: Day = 1
value: 1
day-example-3:
summary: Day = 14
value: 14
- name: month
in: query
schema:
oneOf:
- type: integer
- type: 'null'
type: integer
maximum: 12
minimum: 1
title: month
description: Filter by the Month of the Holiday
examples:
- null
- 1
- 5
description: Filter by the Month of the Holiday
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
month-example-1:
summary: 'null: Disable this filter'
month-example-2:
summary: Month = 1
value: 1
month-example-3:
summary: Month = 5
value: 5
responses:
'200':
description: Request fulfilled, document follows
headers: {}
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Holiday'
type: array
'400':
description: Bad request syntax or unsupported method
content:
application/json:
schema:
properties:
status_code:
type: integer
detail:
type: string
extra:
additionalProperties: {}
type:
- 'null'
- object
- array
type: object
required:
- detail
- status_code
description: Validation Exception
examples:
- status_code: 400
detail: Bad Request
extra: {}
deprecated: false
/api/v1/holidays/{year}:
get:
tags:
- Holidays
summary: Holidays of a Year
operationId: ApiV1HolidaysYearHolidaysYear
parameters:
- name: year
in: path
schema:
type: integer
maximum: 9999.0
minimum: 1.0
title: year
description: Year
examples:
- 2025
- 2026
description: Year
required: true
deprecated: false
examples:
year-example-1:
summary: Year 2025
value: 2025
year-example-2:
summary: Year 2026
value: 2026
- name: description
in: query
schema:
oneOf:
- type: string
- type: 'null'
type: string
minLength: 2
title: description
description: 'Case insensitive textual search. Supports wildcards. NB: Accents are respected'
examples:
- null
- trô
- Trava
- Amaz
description: 'Case insensitive textual search. Supports wildcards. NB: Accents are respected'
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
description-example-1:
summary: 'null: Disable this filter'
description-example-2:
summary: Search `Fête du trône`
value: trô
description-example-3:
summary: Search `Fête du travail`
value: Trava
description-example-4:
summary: Search `Nouvel An Amazigh`
value: Amaz
- name: day
in: query
schema:
oneOf:
- type: integer
- type: 'null'
type: integer
maximum: 31
minimum: 1
title: day
description: Filter by the Day of the Holiday
examples:
- null
- 1
- 14
description: Filter by the Day of the Holiday
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
day-example-1:
summary: 'null: Disable this filter'
day-example-2:
summary: Day = 1
value: 1
day-example-3:
summary: Day = 14
value: 14
- name: month
in: query
schema:
oneOf:
- type: integer
- type: 'null'
type: integer
maximum: 12
minimum: 1
title: month
description: Filter by the Month of the Holiday
examples:
- null
- 1
- 5
description: Filter by the Month of the Holiday
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
month-example-1:
summary: 'null: Disable this filter'
month-example-2:
summary: Month = 1
value: 1
month-example-3:
summary: Month = 5
value: 5
- name: holiday_type
in: query
schema:
$ref: '#/components/schemas/CalHolidayType'
description: 'There are Three Types of holidays:
- **Religious**: Include only Religious holidays. i.e: Eid el fitr, ...
- **National**: Include only National holidays. i.e: Fête du travail, Fête du trône, ...
- **Exceptional**: Include only Exceptional holidays.
- **ND::Null**: Disable this filter'
required: false
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
holiday_type-example-1:
summary: 'null: Disable this filter'
value: ND
responses:
'200':
description: Request fulfilled, document follows
headers: {}
content:
application/json:
schema:
items:
$ref: '#/components/schemas/Holiday'
type: array
'400':
description: Bad request syntax or unsupported method
content:
application/json:
schema:
properties:
status_code:
type: integer
detail:
type: string
extra:
additionalProperties: {}
type:
- 'null'
- object
- array
type: object
required:
- detail
- status_code
description: Validation Exception
examples:
- status_code: 400
detail: Bad Request
extra: {}
deprecated: false
/api/v1/holidays/is-holiday:
get:
tags:
- Holidays
summary: Check if a date is a Holiday
operationId: ApiV1HolidaysIsHolidayIsHoliday
parameters:
- name: date
in: query
schema:
type: string
format: date
title: date
description: Check if this date is a Holiday
examples:
- '2025-07-22'
- '2025-12-02'
- '2026-11-06'
description: Check if this date is a Holiday
required: true
deprecated: false
allowEmptyValue: false
allowReserved: false
examples:
date-example-1:
summary: Date 1
value: '2025-07-22'
date-example-2:
summary: Date 2
value: '2025-12-02'
date-example-3:
summary: Marche Verte
value: '2026-11-06'
responses:
'200':
description: Request fulfilled, document follows
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/IsHoliday'
'400':
description: Bad request syntax or unsupported method
content:
application/json:
schema:
properties:
status_code:
type: integer
detail:
type: string
extra:
additionalProperties: {}
type:
- 'null'
- object
- array
type: object
required:
- detail
- status_code
description: Validation Exception
examples:
- status_code: 400
detail: Bad Request
extra: {}
deprecated: false
components:
schemas:
Holiday:
properties:
description:
type: string
day:
type: integer
month:
type: integer
date:
type: 'null'
holiday_type:
$ref: '#/components/schemas/CalHolidayType'
country_code:
type: string
default: MA
status:
$ref: '#/components/schemas/CalHolidayStatus'
type: object
required:
- description
title: Holiday
IsHoliday:
properties:
date:
type: string
format: date
is_holiday:
type: boolean
description:
type: string
holiday_type:
$ref: '#/components/schemas/CalHolidayType'
status:
$ref: '#/components/schemas/CalHolidayStatus'
country_code:
type: string
type: object
required:
- country_code
- date
- description
- holiday_type
- is_holiday
- status
title: IsHoliday
CalHolidayStatus:
type: string
enum:
- ND
- Estimated
- Official
title: CalHolidayStatus
description: "Represents the status of religious holidays which are based on moon sightings.\n\n At the start of the year, Religious holydays are **Estimated**. When the official moon sighting is confirmed the status is changed to **Official**\n\n NB: The change may **shift the `Estimated` date by ONE DAY**\n\n All other Holiday types are Official by default\n\n Attributes:\n - ND: Not defined for the entity or unknown by us (very unlikely)\n - Official (str): The holiday is validated and thus Official\n - Estimated (str): The holiday is estimated before the moon sighting\n "
CalHolidayType:
type: string
enum:
- ND
- Religious
- National
- Exceptional
title: CalHolidayType
description: 'There are Three Types of holidays:
- **Religious**: Include only Religious holidays. i.e: Eid el fitr, ...
- **National**: Include only National holidays. i.e: Fête du travail, Fête du trône, ...
- **Exceptional**: Include only Exceptional holidays.
- **ND::Null**: Disable this filter'
default: ND
examples:
- ND
securitySchemes:
apiKey:
type: apiKey
description: API Key authentication and authorization.
name: X-API-KEY
in: header
sessionCookie:
type: apiKey
description: Session cookie authentication.
name: session
in: cookie
externalDocs:
url: https://docs.calendar-api.ma
description: Documentation externe de l'API