Skip to main content

Calendars

Calendars say which dates or times a timeseries has a value for (daily, business days, hourly and so on), which days are holidays, and when futures contracts expire.


Calendar​

Service: Calendar (calendar/v1/{source}), versioned. A calendar is a wrapper with the definition in calendar.

FieldTypeRequiredWhat it is
_idStringYesThe calendar code. Public calendars start with #
_typeStringYesVarCalendar
nameStringNoThe name of the calendar
calendarObjectYesThe definition, see below

The definition always has these fields:

FieldTypeWhat it is
_typeStringThe kind of calendar, for example DailyCalendar, BusinessCalendar, HolidayCalendar, MonthlyCalendar, IntradayCalendar, SparseCalendar
_idStringThe calendar code
_nameStringThe name
intradayBooleanOutput: true if the calendar has more than one value a day

The other fields depend on the kind. See Calendars for the kinds and their settings, for example period, holidayCalendarCode and timezoneCode for an intraday calendar.


Holiday calendar​

A holiday calendar is a calendar whose definition has _type HolidayCalendar and a list of rules. Each rule names the holiday and says when it falls.

FieldTypeWhat it is
ruleStringAlways HolidayCalendar
rulesArrayThe holiday rules

Holiday rules​

Every rule has rule (the kind of rule), name and an optional code and options.

ruleFieldsWhat it means
Actualdom, month, and optionally todom, tomonthThe same date (or dates) every year, for example 25 December
EverydayEvery week on a day, for example SATURDAY
Ordinalordinal, day, monthThe nth day of a month, for example the first MONDAY in May
Lastday, monthThe last day of a month, for example the last MONDAY in May
Penultimateday, monthThe second last day of a month
GoodFriday, EasterSunday, EasterMonday, MaundyThursday, AscensionDay, Pentecost, WhitMonday, CorpusChristi, VictoriaDaynoneNamed holidays, see Holiday calendar

options change when a rule applies:

FieldTypeWhat it is
shiftIntegerDays to move the holiday
shiftOnSaturday ... shiftOnFridayIntegerDays to move the holiday when it falls on that day, for example 2 on Saturday to move it to Monday
validFromYear, validToYearIntegerThe years the rule applies to, default 0 and 9999
repeats, repeatStartYearIntegerThe rule applies every repeats years from repeatStartYear
{
"_id": "NGE_HOLIDAYS",
"_type": "VarCalendar",
"name": "Northgate office holidays",
"calendar": {
"_type": "HolidayCalendar",
"_id": "NGE_HOLIDAYS",
"_name": "Northgate office holidays",
"rule": "HolidayCalendar",
"rules": [
{"rule": "Every", "name": "Saturday", "day": "SATURDAY"},
{"rule": "Every", "name": "Sunday", "day": "SUNDAY"},
{"rule": "Actual", "name": "Christmas Day", "dom": 25, "month": 12, "options": {"shiftOnSaturday": 2, "shiftOnSunday": 2}},
{"rule": "Actual", "name": "Boxing Day", "dom": 26, "month": 12, "options": {"shiftOnSaturday": 2, "shiftOnSunday": 2}},
{"rule": "GoodFriday", "name": "Good Friday"},
{"rule": "Ordinal", "name": "Early May bank holiday", "ordinal": 1, "day": "MONDAY", "month": 5}
]
}
}

When you read a holiday calendar, every option is written, with its default value where you did not set it.

tip

When you save a holiday calendar, you can give rules as a list of rule strings in ODSL syntax, and they are turned into rule objects for you.


Expiry calendar​

An expiry calendar works out when contracts stop trading, from rules for each kind of contract. Service: Expiry calendar (expiry/v1/{source}), versioned.

FieldTypeRequiredWhat it is
_idStringYesThe expiry calendar code, for example #REOMHENG
_typeStringYesVarExpiryCalendar
nameStringNoThe name
calendarObjectYesThe definition, see below

The definition:

FieldTypeWhat it is
_typeStringExpiryCalendar, or FinancialExpiryCalendar for currency forwards
_idStringThe code
nameStringThe name
tradingCalendarCodeStringThe calendar of trading days
deliveryCalendarCodeStringOptional: the calendar of delivery days
rulesObjectThe rules, in map: for each kind of contract (ALL, Day, Week, Month, Quarter, Season, Year and so on) a list of rules

Each rule in the list:

FieldTypeWhat it is
ruleObjectThe rule: rule is GrammarExpiryRule and code is the rule in words, see Expiry calendar
dateDateOptional: the date the rule starts or stops applying
beforeBooleanWith date: true if the rule applies before the date, false if after it
{
"_id": "NGE_EOM",
"_type": "VarExpiryCalendar",
"name": "Northgate end of previous month",
"calendar": {
"_type": "ExpiryCalendar",
"_id": "NGE_EOM",
"name": "Northgate end of previous month",
"tradingCalendarCode": "#HENG",
"rules": {
"map": {
"ALL": [
{"before": false, "rule": {"rule": "GrammarExpiryRule", "code": "go to the end of the previous month"}}
]
}
}
}
}

A financial expiry calendar has tradingCalendarCode, crossCode and baseCode (the holiday calendars of the two currencies) and offset (the settlement days) instead of rules.