Calendar Service
The calendar resource contains all the public and private calendars
Calendar REST APIβ
The Calendar REST API is a full CRUD API allowing you to search and filter calendars as well as update, version and delete them. It is accessed through the following URL:
https://api.opendatadsl.com/api/calendar
The API consists of the following calls:
| Method | Path | Example | Description |
|---|---|---|---|
| GET | Get the build information for this service | ||
| GET | {release}/{source} | 'v1/public' 'v1/private' | List public or private calendars |
| GET | {release}/{source}/{key} | v1/private/TEST | Retrieve a single calendar using itβs unique id |
| GET | {release}/{source}/{key}/{version} | v1/private/TEST/1 | Retrieve a version of a single calendar |
| GET | {release}/{source}/{key}/* | v1/private/TEST/* | Get a list of versions for a specific calendar |
| PUT | {release}/{source}/{key}/{version}/{tag} | v1/private/TEST/1/PROD | Tag a version with a name (which can be used instead of the version number when retrieving it) |
| POST | {release} | v1 | Create or update an calendar, the calendar is the body of the POST request |
| DELETE | {release}/{source}/{key} | v1/private/TEST | Rollback to the previous version of a calendar, if it is the only version then the calendar will be deleted |
| DELETE | {release}/{source}/{key}/{version} | v1/private/TEST/1 | Delete a specific version of a calendar |
| DELETE | {release}/{source}/{key}/* | v1/private/TEST/* | Fully delete a calendar, including all versions |
Functionsβ
Functions are run with the _function query parameter on a GET request:
| Function | Example | Description |
|---|---|---|
| holidays | v1/private/TEST?_function=holidays&year=2026,2027 | The holidays of a holiday calendar for the years given (comma separated, default this year): a list of date and name |
| indexes | v1/private/TEST?_function=indexes&start=2026-01-01&end=2026-12-31 | The dates of a calendar between start and end (default this calendar year) |
| holiday-report | v1/private?_function=holiday-report&_id=TEST,TEST2&start=2026-01-01&end=2026-12-31 | The holidays of several holiday calendars between start and end (default today), sorted by date: a data list of _id, date and name |
| index-report | v1/private?_function=index-report&_id=TEST,TEST2&start=2026-01-01&end=2026-01-31 | The dates of several calendars between start and end (default today), sorted by date: a data list of _id and date |
Calendars are read from public when the id starts with #, otherwise from private.
When you create a holiday calendar (_type HolidayCalendar), you can give its rules as a list of rule strings in ODSL syntax, and they are parsed into the calendar for you.
Entitiesβ
Calendar Entityβ
The calendar entity contains the following information:
| Name | Description | Type |
|---|---|---|
| _id | Unique id for the calendar (or object id if this is not the latest version of the calendar) | String |
| _type | The type of the entity - always VarCalendar | String |
| calendar | The definition of the calendar | Calendar |
| _oid | The id of the calendar - will match _id if this is the latest version of the calendar | String |
| _timestamp | Timestamp of when this calendar version was created | String(DateTime) |
| _user | The user id (email) of the user that created this calendar verision | String |
| _tag | A list of version tag names for this calendar version | String[] |
| _version | The version number of this calendar version | int |
HolidayCalendarβ
The entity definition of a holiday calendar:
| Name | Description | Type |
|---|---|---|
| _id | Unique id for the holiday calendar | String |
| _type | The entity type - always HolidayCalendar | String |
| rule | The rule type - always Holiday Calendar | String |
| rules | The list of rules | HolidayRule[] |
HolidayRuleβ
The main entity definition of a holiday rule:
| Name | Description | Type |
|---|---|---|
| rule | The type of rule | String |
| code | The code name of the rule | String |
| name | The name of the rule | String |
A holiday rule can contain more fields based on the type - the following entity definitions extend the above HolidayRule entity:
HolidayRule - Everyβ
Defining a specific day of the week to always be a holiday
| Name | Description | Type |
|---|---|---|
| day | The day name | String |
HolidayRule - Actualβ
Defining a specific day or days of the year to always be a holiday
| Name | Description | Type |
|---|---|---|
| dom | The start day of the month | int |
| todom | The end day of the month | int |
| month | The start month | int |
| tomonth | The end month | int |
| options | A list of options that modify this rule | options |
HolidayRule - Lastβ
Defining the last specific named day of a specific month
| Name | Description | Type |
|---|---|---|
| day | The named day | String |
| month | The month number | int |
| options | A list of options that modify this rule | options |
HolidayRule - Ordinalβ
Defining the nth specific named day or a specific month
| Name | Description | Type |
|---|---|---|
| ordinal | The ordinal or nth specific day of the month | int |
| day | The named day | String |
| month | The month number | int |
| options | A list of options that modify this rule | options |
HolidayRule - Namedβ
There are also certain fixed named holidays - see Holiday Calendar
Optionsβ
The options definition for modifying a rule
| Name | Description | Type |
|---|---|---|
| shiftOnSaturday | The number of days to move backwards or forwards if the holiday lands on a Saturday | int |
| shiftOnSunday | The number of days to move backwards or forwards if the holiday lands on a Sunday | int |
| shiftOnMonday | The number of days to move backwards or forwards if the holiday lands on a Monday | int |
| validFromYear | The first year that this rule is valid from | int |
| validToYear | The last year that this rule is valid to | int |
| repeats | The repeats every n years value | int |
| repeatStartYear | The year in which the repeats value starts | int |