openapi: 3.2.0 info: title: Calendar Business Days 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: Business Days description: National Open business days x-tag-expanded: false paths: /api/v1/bdays/{year}/{month}: get: tags: - Business Days summary: BDays by month operationId: ApiV1BdaysYearMonthBdaysMonth 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: month in: path schema: oneOf: - type: integer - type: 'null' maximum: 12 minimum: 1 description: Month of the Year examples: - 1 - 7 description: Month of the Year required: true deprecated: false examples: month-example-1: summary: January value: 1 month-example-2: summary: July value: 7 responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/SerieDatesEng' '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/bdays/next: get: tags: - Business Days summary: Next day operationId: ApiV1BdaysNextBdaysNext parameters: - name: date in: query schema: type: string format: date examples: - '2025-11-17' - '2025-11-21' required: true deprecated: false allowEmptyValue: false allowReserved: false examples: adate-example-1: summary: Day before a holiday `fête de l'independance` value: '2025-11-17' adate-example-2: summary: A Friday value: '2025-11-21' responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/NextDate' '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/bdays/previous: get: tags: - Business Days summary: Previous day operationId: ApiV1BdaysPreviousBdaysPrevious parameters: - name: date in: query schema: type: string format: date examples: - '2025-11-19' - '2025-11-24' required: true deprecated: false allowEmptyValue: false allowReserved: false examples: adate-example-1: summary: Day after a holiday `fête de l'independance` value: '2025-11-19' adate-example-2: summary: A Monday value: '2025-11-24' responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/PreviousDate' '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/bdays/{year}: get: tags: - Business Days summary: BDays by year operationId: ApiV1BdaysYearBdaysYear 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 responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/SerieDatesEng' '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/bdays/count: get: tags: - Business Days summary: Count Business Days operationId: ApiV1BdaysCountCountBdays parameters: - name: start in: query schema: type: string format: date required: true deprecated: false allowEmptyValue: false allowReserved: false - name: end in: query schema: type: string format: date required: true deprecated: false allowEmptyValue: false allowReserved: false responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/DaysCount' '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/bdays/between: get: tags: - Business Days summary: Business Days between dates operationId: ApiV1BdaysBetweenDatesBetween parameters: - name: start in: query schema: type: string format: date required: true deprecated: false allowEmptyValue: false allowReserved: false - name: end in: query schema: type: string format: date required: true deprecated: false allowEmptyValue: false allowReserved: false responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/SerieDatesEng' '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/bdays/span/month: get: tags: - Business Days summary: Span Month operationId: ApiV1BdaysSpanMonthSpanMonth parameters: - name: year in: query schema: type: integer maximum: 9999.0 minimum: 1.0 title: year description: Year examples: - 2025 - 2026 description: Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: year-example-1: summary: Year 2025 value: 2025 year-example-2: summary: Year 2026 value: 2026 - name: month in: query schema: type: integer maximum: 12.0 minimum: 1.0 description: Month of the Year examples: - 1 - 7 description: Month of the Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: month-example-1: summary: January value: 1 month-example-2: summary: July value: 7 responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/CalSpan' '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/bdays/span/quarter: get: tags: - Business Days summary: Span Quarter operationId: ApiV1BdaysSpanQuarterSpanQuarter parameters: - name: year in: query schema: type: integer maximum: 9999.0 minimum: 1.0 title: year description: Year examples: - 2025 - 2026 description: Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: year-example-1: summary: Year 2025 value: 2025 year-example-2: summary: Year 2026 value: 2026 - name: quarter in: query schema: type: integer maximum: 4.0 minimum: 1.0 description: Quarter of the Year examples: - 1 - 3 description: Quarter of the Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: quarter-example-1: summary: Q1 value: 1 quarter-example-2: summary: Q3 value: 3 responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/CalSpan' '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/bdays/span/semester: get: tags: - Business Days summary: Span Semester operationId: ApiV1BdaysSpanSemesterSpanSemester parameters: - name: year in: query schema: type: integer maximum: 9999.0 minimum: 1.0 title: year description: Year examples: - 2025 - 2026 description: Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: year-example-1: summary: Year 2025 value: 2025 year-example-2: summary: Year 2026 value: 2026 - name: semester in: query schema: type: integer maximum: 2.0 minimum: 1.0 description: Semester of the Year examples: - 1 - 2 description: Semester of the Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: semester-example-1: summary: S1 value: 1 semester-example-2: summary: S2 value: 2 responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/CalSpan' '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/bdays/span/year: get: tags: - Business Days summary: Span Year operationId: ApiV1BdaysSpanYearSpanYear parameters: - name: year in: query schema: type: integer maximum: 9999.0 minimum: 1.0 title: year description: Year examples: - 2025 - 2026 description: Year required: true deprecated: false allowEmptyValue: false allowReserved: false examples: year-example-1: summary: Year 2025 value: 2025 year-example-2: summary: Year 2026 value: 2026 responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/CalSpan' '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: DaysCount: properties: start_date: type: string format: date end_date: type: string format: date count: type: integer freq: $ref: '#/components/schemas/CalFreq' type: object required: - count - end_date - freq - start_date title: DaysCount CalMode: type: string enum: - D - W title: CalMode description: "The Mode used by the Fin Calendar to calulate the reference dates of dynamic periods. i.e: 3:M, 23:W, 12:Y, ...\n\n Enums:\n - D: The calculation is based on open `dailies` dates. Similar to any Business days based calendar\n - W: The calculation is based on the `weeklies` (**Fridays**). Returns the last weekdate related to the provided `period`\n " CalFreq: type: string enum: - ND - D - W - M - Q - S - Y title: CalFreq description: "Frequency\n\n Enums:\n - D: DAILY\n - W: WEEKLY\n - M: MONTHLY\n - Q: QUARTERLY\n - S: SEMI-ANNUALLY\n - Y: YEARLY\n " SerieDatesEng: properties: ref: type: string min_date: type: string format: date max_date: type: string format: date freq: $ref: '#/components/schemas/CalFreq' nitems: type: integer serie: items: type: string format: date type: array type: object required: - ref title: SerieDatesEng PreviousDate: properties: date: type: string format: date previous_date: type: string format: date type: object required: - date - previous_date title: PreviousDate NextDate: properties: date: type: string format: date next_date: type: string format: date type: object required: - date - next_date title: NextDate CalSpan: properties: start_date: type: string format: date end_date: type: string format: date year: type: integer semester: type: integer quarter: type: integer month: type: integer mode_calendar: $ref: '#/components/schemas/CalMode' country_code: type: string type: object required: - country_code - end_date - mode_calendar - month - quarter - semester - start_date - year title: CalSpan 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