Japanese Holidays Are Harder Than You Think: Substitute Holidays, Business Days & Wareki

Nakayama Yuta — Thu, 10 Sep 2026 13:30:25 +0000

This is a draft for dev.to. When you're happy with it, set published: false to published: true.
Replace YOUR_RAPIDAPI_KEY and the host name with the real values from your API's Code Snippets page on RapidAPI.

Working with Japanese dates is surprisingly painful

If you're building (or localizing) a product for the Japanese market, you'll eventually hit a wall that looks trivial but isn't: Japanese public holidays and business-day calculations.

"Set the invoice due date to 3 business days later, skipping weekends and holidays."
"Estimate the delivery date, skipping national holidays."
"Show dates in the Japanese era format (Reiwa 8)."

Each sounds easy. Then you try to implement Japanese holiday rules correctly, and you fall straight into a swamp. Let's look at why, and then at a way to get it done accurately without maintaining all of it yourself.

Why it's hard — four traps

Trap 1: The equinox holidays move every year

Vernal Equinox Day (春分の日, March) and Autumnal Equinox Day (秋分の日, September) are astronomically determined, so the exact date shifts year to year. You can't hard-code them. A common approximation (valid ~1980–2099):

// Vernal Equinox Day (March)
const vernal = (y) =>
  Math.floor(20.8431 + 0.242194 * (y - 1980) - Math.floor((y - 1980) / 4));
// Autumnal Equinox Day (September)
const autumnal = (y) =>
  Math.floor(23.2488 + 0.242194 * (y - 1980) - Math.floor((y - 1980) / 4));

Trap 2: "Happy Monday" holidays

Coming-of-Age Day (2nd Monday of January), Marine Day (3rd Monday of July), Respect-for-the-Aged Day (3rd Monday of September) and Sports Day (2nd Monday of October) float to a specific Monday. You need weekday math, not fixed dates.

Trap 3: Substitute holidays (振替休日)

When a public holiday falls on a Sunday, a following weekday becomes a holiday — and it is not always the next Monday. Take Japan's Golden Week in 2026: May 3rd (Constitution Day) is a Sunday, so the substitute skips over the May 4th and 5th holidays and lands on May 6th. If you naively code "Sunday → next day," you get it wrong.

Trap 4: The "Citizen's Holiday" (国民の休日)

A weekday sandwiched between two public holidays also becomes a holiday. The classic case is September 22, 2026: it sits between Respect-for-the-Aged Day (Sep 21) and Autumnal Equinox Day (Sep 23), so that Tuesday becomes a holiday too. If you don't know this rule exists, you will miss it.

On top of all that, one-off legislation occasionally moves holidays for a single year (as in 2020 and 2021 for the Olympics). Just maintaining an accurate holiday calendar is real work.

The shortcut: solve it with an API

Writing and maintaining all of the above yourself is a lot. So here's an API that returns Japanese holidays, business-day math, and era (Wareki) conversion out of the box.

Japanese Holidays and Business Day API (on RapidAPI)

Holidays are computed according to the Japanese Cabinet Office's official definition of public holidays, and it covers substitute holidays, citizen's holidays, and the Olympic-year exceptions. Five endpoints:

Endpoint	Purpose
`GET /v1/holidays?year=2026`	All holidays for a year
`GET /v1/holidays/check?date=2026-09-22`	Is this date a holiday? (with type)
`GET /v1/business-days/add?date=2026-05-01&days=3`	Add N business days (negative = before)
`GET /v1/business-days/count?from=...&to=...`	Business days in a range
`GET /v1/wareki?date=2026-09-10`	Gregorian → Japanese era

Try it

Requests go through RapidAPI. Copy the host and X-RapidAPI-Key from the Code Snippets tab on the API's RapidAPI page (the host may differ slightly).

⚠️ Keep your API key out of source and public posts — read it from an environment variable.

curl

curl --request GET \
  --url 'https://japanese-holidays-and-business-day-api.p.rapidapi.com/v1/holidays/check?date=2026-09-22' \
  --header 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  --header 'X-RapidAPI-Host: japanese-holidays-and-business-day-api.p.rapidapi.com'

Response:

{
  "date": "2026-09-22",
  "is_holiday": true,
  "name": "国民の休日",
  "type": "national_gap"
}

type is one of national_holiday, substitute, or national_gap, so you can branch on the kind of holiday.

JavaScript

const HOST = "japanese-holidays-and-business-day-api.p.rapidapi.com";
const KEY = process.env.RAPIDAPI_KEY;

async function checkHoliday(date) {
  const res = await fetch(`https://${HOST}/v1/holidays/check?date=${date}`, {
    headers: { "X-RapidAPI-Key": KEY, "X-RapidAPI-Host": HOST },
  });
  return res.json();
}

console.log(await checkHoliday("2026-09-22"));
// { date: '2026-09-22', is_holiday: true, name: '国民の休日', type: 'national_gap' }

Python

import os
import requests

HOST = "japanese-holidays-and-business-day-api.p.rapidapi.com"
headers = {
    "X-RapidAPI-Key": os.environ["RAPIDAPI_KEY"],
    "X-RapidAPI-Host": HOST,
}

res = requests.get(
    f"https://{HOST}/v1/business-days/add",
    headers=headers,
    params={"date": "2026-05-01", "days": 3},
)
print(res.json())
# {'date': '2026-05-01', 'days': 3, 'result_date': '2026-05-11'}

Note that 3 business days after 2026-05-01 (Friday) lands on 2026-05-11 (Monday) — correctly skipping the weekend and the Golden Week holidays (including the May 6th substitute holiday).

Era (Wareki) conversion

curl '.../v1/wareki?date=2026-09-10' \
  -H 'X-RapidAPI-Key: YOUR_RAPIDAPI_KEY' \
  -H 'X-RapidAPI-Host: japanese-holidays-and-business-day-api.p.rapidapi.com'
# → { "date": "2026-09-10", "era": "令和", "year": 8, "text": "令和8年" }

Notes & limits

Holidays follow the Japanese Cabinet Office definition of public holidays. Supported range is 1980–2099, most accurate from 2020 onward.
Responses include a data-source attribution field.
There's a free tier to try it out, plus paid plans for production use.

Wrapping up

Japanese holidays and business days look trivial but hide real complexity: equinox dates, Happy Monday holidays, substitute holidays, and citizen's holidays. Instead of building and maintaining all of it yourself, you can offload it to an API and get an accurate answer in a single call.

If you're dealing with Japanese date logic in your app, give it a try.

👉 Japanese Holidays and Business Day API — search "Japanese Holidays" on RapidAPI.

👉 Japanese Holidays and Business Day API on RapidAPI

DEV Community: Nakayama Yuta