Exchange Calendars

Overview

calendar is a Golang package that provides exchange-specific calendar functionality. It enables you to manage market holidays, business days, early closes, and sessions defined by Market Identifier Codes (MIC) for various financial exchanges globally.

Features

• Business Day Calculations: Check if a date is a business day, holiday, or early close.
• Custom Holidays: Define and manage custom holidays (recurring or one-time events).
• Exchange Sessions: Handle exchange sessions with customizable open/close times.
• Multi-Year Support: Supports predefined calendars for financial exchanges over several years.
• Market Identifier Code: Exchange calendars are defined by their ISO-10383 Market Identifier Code (MIC).

Installation

Install the package by running:

go get github.com/scmhub/calendar

Usage

Basic example

import (
    "fmt"
    "time"
    "github.com/scmhub/calendar"
)

func main() {
    // Create a calendar with default years (current year ±5 years)
	nyse := calendar.XNYS()

    // Or create a calendar with a custom start and end year
	customCal := calendar.XNYS(2010, 2035) // From 2010 to 2035

    // Check if today is a business day
     today := time.Now()
    if nyse.IsBusinessDay(today) {
        fmt.Println("Today is a business day.")
    } else {
        fmt.Println("Today is not a business day.")
    }

    // Get the next business day
    nextBusinessDay := nyse.NextBusinessDay(today)
    fmt.Printf("Next business day: %v\n", nextBusinessDay)

	// Check if Black Friday 2030 is an early close
	blackFriday := time.Date(2030, time.November, 29, 0, 0, 0, 0, calendar.NewYork)
	fmt.Println(customCal.IsEarlyClose(blackFriday)) // Outputs: true
}

Print specific calendar

import (
    "fmt"
    "github.com/scmhub/calendar"
)

func main() {
    // Load the New York Stock Exchange (XNYS) calendar
    nyse := calendar.XNYS()

    nyse.SetYears(2021,2022)

    fmt.Print(nyse)
}

Output

Calendar New York Stock Exchange:
        2021-Jan-01 Fri    New Year's Day
        2021-Jan-18 Mon    Martin Luther King Jr. Day
        2021-Feb-15 Mon    Presidents' Day
        2021-Apr-02 Fri    Good Friday
        2021-May-31 Mon    Memorial Day
        2021-Jul-05 Mon    Independence Day
        2021-Sep-06 Mon    Labor Day
        2021-Nov-25 Thu    Thanksgiving Day
        2021-Nov-26 Fri    Black Friday
        2021-Dec-24 Fri    Christmas Day
        2022-Jan-17 Mon    Martin Luther King Jr. Day
        2022-Feb-21 Mon    Presidents' Day
        2022-Apr-15 Fri    Good Friday
        2022-May-30 Mon    Memorial Day
        2022-Jun-20 Mon    Juneteenth National Independence Day
        2022-Jul-04 Mon    Independence Day
        2022-Sep-05 Mon    Labor Day
        2022-Nov-24 Thu    Thanksgiving Day
        2022-Nov-25 Fri    Black Friday
        2022-Dec-26 Mon    Christmas Day

Creating Holidays & Calendars

// Create Recurring Holidays
MemorialDay = &Holiday{
    Name:       "Memorial Day",
    Month:      time.May,
    Weekday:    time.Monday,
    NthWeekday: -1,
    calc:       CalcNthWeekday,
}
IndependenceDay = &Holiday{
    Name:       "Independence Day",
    Month:      time.July,
    Day:        4,
    observance: nearestWorkday,
    calc:       CalcDayOfMonth,
}

// Create Non Recurring Holidays
// September 11 - september 11, 2001
SeptemberEleven = &Holiday{
    Name:   "Sepember 11",
    Month:  time.September,
    Day:    11,
    OnYear: 2001,
    calc:   CalcDayOfMonth,
}

// September 11 -14 range
SeptemberElevenDays = []*Holiday{
    SeptemberEleven,
    SeptemberEleven.Copy("Sepember 11 day 2").SetOffset(1),
    SeptemberEleven.Copy("Sepember 11 day 3").SetOffset(2),
    SeptemberEleven.Copy("Sepember 11 day 4").SetOffset(3),
}

// Copy an Holiday and set observance
NewYear.Copy("New Year's Day").SetObservance(sundayToMonday)

// Create a Calendar
c := NewCalendar("New York Stock Exchange", NewYork, 2010, 2025)
// Set Session
c.SetSession(&Session{
    EarlyOpen:  7 * time.Hour,
    Open:       9*time.Hour + 30*time.Minute,
    Close:      16 * time.Hour,
    EarlyClose: 13 * time.Hour,
    LateClose:  20 * time.Hour,
})
// Add Recurring Holidays
c.AddHolidays(
    NewYear.Copy().SetObservance(sundayToMonday),
    MLKDay,
    PresidentsDay,
    GoodFriday,
    MemorialDay,
    JuneteenthDay,
    IndependenceDay,
    LaborDay,
    ThanksgivingDay,
    ChristmasDay.Copy().SetObservance(nearestWorkday),
)
// Add Non Recurring Holidays
c.AddHolidays(USNationalDaysOfMourning...)
c.AddHolidays(SeptemberElevenDays...)
c.AddHolidays(HurricaneSandyDays...)
// Early Closing
c.AddEarlyClosingDays(
    BeforeIndependenceDay.Copy().SetObservance(onlyOnWeekdays(time.Monday, time.Tuesday, time.Thursday)),
    AfterIndependenceDay.Copy().SetBeforeYear(2013).SetObservance(onlyOnWeekdays(time.Friday)),
    BeforeIndependenceDay.Copy().SetAfterYear(2013).SetObservance(onlyOnWeekdays(time.Wednesday)),
    BlackFriday,
    ChristmasEve.Copy().SetObservance(exeptOnWeekdays(time.Friday)), // Overlap Christmas day observance if friday
)

Existing Calendar

Market place	Exchange	MIC
New York	New York Stock Exchange	XNYS	✅
New York	NASDAQ	XNAS	✅
Chicago	CBOE	XCBO	✅
Chicago	CBOE Futures Exchange	XCBF	✅
Toronto	Toronto Stock Exchange	XTSE
Mexico	Mexican Stock Exchange	XMEX
Sao Paulo	BMF Bovespa	BVMF
London	London Stock Exchange	XLON	✅
Amsterdam	Euronext Amsterdam	XAMS	✅
Brussels	Euronext Brussels	XBRU	✅
Lisbon	Euronext Lisbon	XLIS	✅
Paris	Euronext Paris	XPAR	✅
Milan	Euronext Milan - Borsa Italiana	XMIL	✅
Madrid	Bolsa de Madrid	XMAD	✅
Franckfurt	Deutsche Boerse	XFRA	✅
Franckfurt	Xetra	XETR	✅
Zurich	SIX Swiss Exchange	XSWX	✅
Mumbai	Bombay Stock Exchange	XBOM
Bangkok	Stock Exchange of Thailand	XBKK
Singapore	Singapore Exchange	XSES	✅
Hong Kong	Hong Kong Stock Exchange	XHKG	✅
Shenzhen	Shenzhen Stock Exchange	XSHE	✅
Shanghai	Shanghai Stock Exchange	XSHG	✅
Seoul	Korea Exchange	XKRX
Tokyo	Japan Exchange Group	XJPX	✅
Sidney	Austrialian Securities Exchange	XASX

API References

Some key functions:

• IsBusinessDay(t time.Time): Returns whether the date is a business day.
• NextBusinessDay(t time.Time): Gets the next business day after the given date.
• AddHolidays(h ...Holiday): Adds holidays to the calendar.
• SetSession(session *Session): Configures open/close times for the exchange.

Contributing

Contributions are welcome! Please submit issues or pull requests to improve the package. For significant changes, open an issue to discuss your ideas first.