# Calendar API (calendrier marocain)

> REST API for the Moroccan economic calendar: national, religious and exceptional public holidays, and open
> business-day calculations. JSON over HTTPS, OpenAPI 3.1 contract, X-API-KEY header auth, and a typed
> first-party Python SDK (pycalendar-api). Built by Unravel Designs (Casablanca) for data engineers wiring
> Moroccan holiday logic into ETL pipelines and orchestrators such as Airflow and Dagster.

Generated by API Evangelist from the provider's published OpenAPI and public site. The provider does not
serve an llms.txt of its own (https://calendar-api.ma/llms.txt -> 404, https://docs.calendar-api.ma/llms.txt -> 404).

Base URL: https://calendar-api.ma
Auth: `X-API-KEY: <your key>` request header. Keys are self-issued from the console; up to 5 keys per account.
Registration is free and requires no payment card. Unauthenticated calls return HTTP 401
`{"status_code":401,"detail":"Auth Header = \`X-API-KEY\` not found in request header"}`.

## Core concepts

- Holiday types: `National` (fixed Gregorian civil dates), `Religious` (Islamic feasts, dated astronomically
  then confirmed by moon sighting), `Exceptional` (ad-hoc government-decreed days and bridges).
- Holiday status: `Official` (confirmed, safe to act on) or `Estimated` (computed, may shift by a day).
  Only religious holidays are ever `Estimated`. Poll until status flips to `Official` before running
  date-critical jobs. The published guidance suggests hourly polling.
- Business day: not a Saturday or Sunday, and not an `Official` holiday of any type. The API treats both
  weekend days as non-working even though only Sunday is the official Moroccan day off.
- CalSpan: the business-day `[start_date, end_date]` bounds of a month, quarter, semester or year — designed
  to chain without gaps or overlap, for direct use in a SQL `BETWEEN`.
- History: religious holidays are qualified from 2006 onward; the provider states coverage will be extended
  back to 1985. Holidays follow an SCD Type 2 history model, so a holiday is absent for years in which it
  was not defined.

## Endpoints

### Holidays
- `GET /api/v1/holidays/is-holiday?date=` — is a date a holiday (operationId `ApiV1HolidaysIsHolidayIsHoliday`)
- `GET /api/v1/holidays` — list all holidays; filters `description`, `holiday_type`, `day`, `month` (`ApiV1HolidaysHolidays`)
- `GET /api/v1/holidays/{year}` — holidays of a year, same filters (`ApiV1HolidaysYearHolidaysYear`)

### Business days
- `GET /api/v1/bdays/next?date=` — next open business day (`ApiV1BdaysNextBdaysNext`)
- `GET /api/v1/bdays/previous?date=` — previous open business day (`ApiV1BdaysPreviousBdaysPrevious`)
- `GET /api/v1/bdays/count?start=&end=` — count business days inclusive (`ApiV1BdaysCountCountBdays`)
- `GET /api/v1/bdays/between?start=&end=` — list business days inclusive (`ApiV1BdaysBetweenDatesBetween`)
- `GET /api/v1/bdays/{year}` — business days of a year (`ApiV1BdaysYearBdaysYear`)
- `GET /api/v1/bdays/{year}/{month}` — business days of a month (`ApiV1BdaysYearMonthBdaysMonth`)
- `GET /api/v1/bdays/span/month?year=&month=` — month bounds (`ApiV1BdaysSpanMonthSpanMonth`)
- `GET /api/v1/bdays/span/quarter?year=&quarter=` — quarter bounds (`ApiV1BdaysSpanQuarterSpanQuarter`)
- `GET /api/v1/bdays/span/semester?year=&semester=` — semester bounds (`ApiV1BdaysSpanSemesterSpanSemester`)
- `GET /api/v1/bdays/span/year?year=` — year bounds (`ApiV1BdaysSpanYearSpanYear`)

### Misc
- `GET /health` — availability; returns `{"api_status":"UP","appname":"calendar-api"}`. No key required.

## Response models

`Holiday`, `IsHoliday`, `NextDate`, `PreviousDate`, `DaysCount`, `CalSpan`, `SerieDatesEng`, `SystemHealth`,
plus the enums `CalHolidayType`, `CalHolidayStatus`, `CalFreq`, `CalMode`. All defined in the OpenAPI
`components.schemas`.

## Errors

Errors are a flat JSON envelope, NOT RFC 9457 problem+json: `{"status_code": <int>, "detail": <string>,
"extra": <object|array|null>}`. The spec declares `400` on every operation except `/health`; `401` is
returned live when the API key header is missing.

## Docs

- API reference (RapiDoc, rendered from the live spec): https://calendar-api.ma/api/v1/docs
- OpenAPI 3.1 document: https://calendar-api.ma/schema/openapi.json (also served at https://calendar-api.ma/apis.json)
- Python SDK docs: https://docs.calendar-api.ma
- Python SDK source: https://gitlab.com/ud-labs/py-calendar-api
- Postman documentation: https://documenter.getpostman.com/view/9897118/2sBYArSrTN
- Holidays guide: https://calendar-api.ma/holidays-api.html
- Business days guide: https://calendar-api.ma/bdays-api.html
- Console (key management, register/login): https://calendar-api.ma/console/
- Contact / support: support@calendar-api.ma — https://calendar-api.ma/contacts.html
- Privacy: https://calendar-api.ma/privacy.html

## Not published

No MCP server, no A2A agent card, no /.well-known documents, no AsyncAPI or webhooks, no GraphQL, no CLI,
no status page, no published rate limits, no pricing page and no versioning/deprecation policy.