Japan Bank Holiday and Gotobi Library (MT5/MT4): User Manual, Functions and Examples
Japan Bank Holiday and Gotobi Library is a free library for MetaTrader 5 and MetaTrader 4. It answers the calendar questions of the yen market inside your own Expert Advisor, indicator or script. This manual is for developers and applies to version 1.00 on both platforms.
What it answers
- Japanese national holidays, including substitute, citizens' and one-off holidays, with the English name of each.
- Japanese bank holidays: Saturdays, Sundays, national holidays and December 31 to January 3. All other days are Tokyo business days.
- Gotobi days: the 5th, 10th, 15th, 20th, 25th and the last day of the month. On a bank holiday the gotobi moves to the previous business day of the same month.
- The Tokyo fixing time, 09:55 Japan time, and server time to Japan time and back. Japan has no summer time (JST = UTC+9).
Years 1980 to 2099. The rules are calculated, so there is no holiday table to update. No DLL, no web requests, no files, no trading functions.
Installation
- On the product page click Free Download (it opens MetaTrader), or find it in Toolbox > Market (in MT4 this window is called Terminal). MT5 and MT4 are separate products.
- The Market installs the library as MQL5\Libraries\Market\Japan Bank Holiday and Gotobi Library.ex5 (MT5) or MQL4\Libraries\Market\Japan Bank Holiday and Gotobi Library MT4.ex4 (MT4). File > Open Data Folder shows these folders.
- Installed products and their updates are in Toolbox > Market > Purchased.
- A library is not attached to a chart. Your own program loads it through the import block.
Importing it
Save the header for your platform in the Include folder and add one line at the top of your program:
- JpMarketCalendar_Market.mqh (MT5): save it in MQL5\Include.
- JpMarketCalendar_Market_MT4.mqh (MT4): save it in MQL4\Include.
#include <JpMarketCalendar_Market.mqh> // MT5 #include <JpMarketCalendar_Market_MT4.mqh> // MT4
Each header imports all 17 functions and defines the summer time rules JP_DST_NONE (0), JP_DST_US (1) and JP_DST_EU (2). If you paste the import block yourself, its first line must match the installed file exactly (two backslashes): #import "Market\\Japan Bank Holiday and Gotobi Library.ex5" (MT5) or #import "Market\\Japan Bank Holiday and Gotobi Library MT4.ex4" (MT4).
Two programs to start with, both without orders:
- JpCalendarDemo.mq5 / JpCalendarDemo_MT4.mq4: a script that prints server and Japan time, the next fixings, and the holidays and gotobi days of the years you choose. If it prints them, the library is installed and imported correctly.
- JpCalendarExample.mq5 / JpCalendarExample_MT4.mq4: an Expert Advisor that shows the gotobi fixing time, the holiday name or the next gotobi with Comment().
All six files compile with 0 errors and 0 warnings. Below is the output of the demo script on an MT5 demo server; the MT4 version prints the same lines.
Function reference
| Function | Returns | Notes |
|---|---|---|
| JpIsBankHoliday(datetime date_jst) | bool | true on Saturdays, Sundays, national holidays and December 31 to January 3. |
| JpIsBusinessDay(datetime date_jst) | bool | true on Tokyo business days. Outside 1980-2099 this and JpIsBankHoliday() both return false. |
| JpIsNationalHoliday(datetime date_jst) | bool | true on national holidays, including substitute, citizens' and one-off holidays. |
| JpHolidayName(datetime date_jst) | string | The English name, for example "Marine Day"; "Bank Holiday" on December 31, January 2 and January 3 unless they are national holidays; "" on other days, also on plain weekends. |
| JpIsGotobi(datetime date_jst) | bool | true on gotobi days, which are always business days. |
| JpGotobiDaysOfMonth(int year, int month, datetime &out[]) | int | Fills a dynamic array with the month's gotobi days (00:00 JST, oldest first) and returns the count; -1 for a static array, a year outside 1980-2099 or a month outside 1-12. |
| JpNextGotobi(datetime from_jst) | datetime | The first gotobi on or after that date (00:00 JST). The day itself counts, also after 09:55. 0 if none. |
| JpPrevGotobi(datetime from_jst) | datetime | The last gotobi on or before that date (00:00 JST). 0 if none. |
| JpTokyoFixing(datetime date_jst) | datetime | 09:55 JST of that day, for any day; the fixing is published on business days only. |
| JpNowJst() | datetime | The current Japan time (from the server time, see below). |
| JpServerToJst(datetime server_time) | datetime | Server time to Japan time with the offset in use. 0 for an invalid time. |
| JpJstToServer(datetime jst) | datetime | Japan time to server time. 0 for an invalid time. |
| JpServerGmtOffsetSeconds() | int | The server's GMT offset now, in seconds. |
| JpSetServerGmtOffset(int seconds) | bool | One offset all year, for example 7200 for GMT+2. |
| JpSetServerTimeZone(int standard_offset_seconds, int dst_rule) | bool | The offset outside summer time and the rule: 0 none, 1 US, 2 EU (+1 hour in summer time). |
| JpSetServerGmtOffsetAuto() | void | Back to the automatic offset (the default). |
| JpLibraryVersion() | string | "1.00" |
Date arguments are Japan time; any time of the day can be passed. Outside 1980-2099 the functions return false, 0, "" or -1. The two setters accept a multiple of 900 seconds from -43200 to 50400; for any other value they print the reason, return false and keep the previous setting.
Examples
Today in Japan:
datetime jst = JpNowJst(); // Japan time now
if(JpIsBankHoliday(jst))
Print("Tokyo banks are closed: ", JpHolidayName(jst)); // "" on a plain weekend
else if(JpIsGotobi(jst) && jst < JpTokyoFixing(jst))
Print("Gotobi morning, fixing at ", TimeToString(JpJstToServer(JpTokyoFixing(jst))), " server time"); The next gotobi fixing that has not passed yet:
datetime jst = JpNowJst();
datetime g = JpNextGotobi(jst); // today counts all day
if(g != 0 && JpTokyoFixing(g) < jst) // today's fixing has passed
g = JpNextGotobi(g + 86400);
Print("Next gotobi fixing: ", TimeToString(JpJstToServer(JpTokyoFixing(g))), " server time"); The gotobi days of one month:
datetime days[]; // must be a dynamic array int n = JpGotobiDaysOfMonth(2027, 5, days); // 5 days: 10, 14, 20, 25 and 31 for(int i = 0; i < n; i++) Print(TimeToString(days[i], TIME_DATE));
Time zones and the Strategy Tester
- Server time is not Japan time: in the demo above the server shows 21:43 on October 13 while it is 03:43 on October 14 in Japan. Convert with JpServerToJst() before you ask about a day, or use JpNowJst().
- The default offset is automatic: TimeTradeServer() - TimeGMT() on MT5, rounded to 15 minutes and read again on every call. Right after the terminal starts it can read 0 for a few seconds.
- MT4 has no TimeTradeServer() and uses TimeCurrent(), the time of the last quote, which can be wrong after start-up or while the market is closed. On MT4, set the offset yourself.
- In the Strategy Tester TimeGMT() returns the server time, so the automatic offset is 0. The library writes one reminder to the tester journal. Set the offset in OnInit().
- The automatic offset is today's offset. For past bars across a summer time change, set the server's rule with JpSetServerTimeZone().
- Settings apply to the program that calls them: call them in OnInit() of each Expert Advisor or indicator.
input int ServerGmtWinter = 2; // server GMT offset outside summer time, in hours
input int ServerDstRule = 1; // summer time rule: 0 none, 1 US, 2 EU
int OnInit()
{
if(!JpSetServerTimeZone(ServerGmtWinter * 3600, ServerDstRule))
return(INIT_PARAMETERS_INCORRECT); // the library printed the reason
return(INIT_SUCCEEDED);
} US rule: second Sunday of March to first Sunday of November (earlier US dates before 2007). EU rule: last Sunday of March to last Sunday of October (September before 1996). A server at GMT+2 in winter and GMT+3 in US summer time is 7200 with rule 1. The demo script shows your server's offset now; your broker can tell you which summer time it follows. To keep the automatic offset live on MT5, call the setter only when MQLInfoInteger(MQL_TESTER) is true, as the example EA does.
Rules used and how they were checked
- Act on National Holidays as amended: fixed dates, Monday holidays (Coming of Age Day and Health and Sports Day from 2000, Marine Day and Respect for the Aged Day from 2003), Mountain Day from 2016, the Emperor's Birthday by era and the moved days of 2020 and 2021.
- Substitute holiday: when a national holiday falls on a Sunday, the next day that is not a national holiday is a holiday (from 2007; before that, only the next day).
- Citizens' holiday: a day between two national holidays (from 1986), for example September 22, 2026.
- One-off holidays: 1989-02-24, 1990-11-12, 1993-06-09, 2019-05-01 and 2019-10-22.
- Equinox days: the standard approximation formula, valid for 1980-2099. The government announces each equinox day in February of the previous year.
- Bank holidays: Saturdays, Sundays, national holidays and December 31 to January 3 (Banking Act); today's rule is applied to every year.
- Gotobi: if the 5th would move into the previous month, that day is already the previous month's month-end gotobi and is listed only there. May 2027 therefore has 5 gotobi days.
- These are the rules in force when version 1.00 was made (October 2026).
Checks before release: both versions compile with 0 errors and 0 warnings; the MT4 version is made from the same source (only the time function differs). All 789 national holidays from 1980 to 2027 match the Cabinet Office list day by day; that list currently ends in 2027. The equinox formula gives the official date in every year up to 2027 and agrees with an astronomical calculation in every year to 2099. The import from the Market path also loads in the Strategy Tester.
Questions developers ask
- My program stops with an error about the library. Check that the library is installed and that the #import line matches the file name exactly. The MT4 file name ends with MT4.
- The Japanese date is one day off in the evening. You passed server time. Convert it with JpServerToJst() first.
- JpGotobiDaysOfMonth() returns -1. Pass a dynamic array ( datetime days[]; ), a year from 1980 to 2099 and a month from 1 to 12.
- Is it fast enough for OnTick()? Yes. Results are cached per year. The cache keeps 2 years, so a loop that jumps between many years is slower.
Product pages: Japan Bank Holiday and Gotobi Library (MT5) and Japan Bank Holiday and Gotobi Library MT4. If something is unclear, send me a private message on MQL5 with the code you use and the last lines of the Experts tab.
