Suggestion: China - Wait until holidays are officially announced

[gwilym]

More information

For China, the API returns schedules for future years the government hasn't announced. As of today, GET /api/v3/PublicHolidays/2027/CN already returns a full 2027 list (New Year, Spring Festival 02-06, Labour Day, Dragon Boat, Mid-Autumn, National Day).

These are computed from ChineseLunisolarCalendar in ChinaHolidayProvider.cs, not from an official source. There's no gate on whether a schedule has been announced, and it emits only the single principal day per festival (no 调休 makeup/observed days).

China's schedule is set annually by the State Council (国务院办公厅关于节假日安排的通知 / Notice from the General Office of the State Council Regarding Holiday Arrangements), published ~Oct–Dec of the prior year. That notice defines the real observed days and makeup workdays. So a predicted year is incomplete by construction and can differ from what's gazetted, and API consumers can't tell prediction from fact.

Is it worthwhile trying to predict a single date like this? I'd suggest not, at least not without something in the data model / API to mark it as unconfirmed.

Note: I'm not in China, nor do I understand Mandarin Chinese, I just happen to be using this data at the moment. I'll defer to anyone with deeper China holiday experience. For my own use, I'm considering skipping this China data altogether given its unconfirmed nature.

[tinohager]

We're dealing with this issue in Australia and Turkey as well. There, we've resolved it by adding the label “Tentative Date.” But I've been wondering myself whether an additional flag like “Tentative: bool” would be useful.

[SISheogorath]

I've been looking around a bit, sadly China doesn't publish their public holidays in machine readable formats at this point (or at least I didn't find any).

But there are some people who nowadays scrape the websites and generate the data in machine readable form: https://github.com/NateScarlet/holiday-cn/tree/master

Maybe it's worth a look to integrate these. Both projects are published as MIT license, which certainly helps.

[zhongzhir]

@gwilym — your write-up matches a concrete gap I've been working on.

You're right that China's observed holiday spans and 调休 makeup workdays only exist after the State Council notice, and that predicting a future year (or emitting only the principal festival day) is incomplete by construction. API consumers also can't tell prediction from gazette.

Disclosure: I publish Working Day Calendar on RapidAPI (owner account @zhongzhir). Design choices that map to what you described:

1. No guessed China makeup days. For CN we encode official State Council notice years only (currently 2025–2026). Unpublished future years are not filled with invented 调休 — the service health payload reports china_unpublished_policy: statutory_only_no_guessed_makeup.
2. Makeup workdays are first-class. Example: 2026-02-14 is a Saturday but an official Spring Festival makeup working day; GET /v1/is-working-day?country=CN&date=2026-02-14 is intended to return working-day = true (the failure mode you called out on mainstream holiday-only APIs).

Honest limits / price: BASIC is free for light trial; PRO is $9.99/mo. It is a hosted working-day + holiday API (plus 节气), not a drop-in Nager.Date replacement, and it does not invent unpublished CN schedules. If you prefer offline/OSS, the NateScarlet/holiday-cn dataset already linked above is the right data layer.

Happy to answer technical questions either way — no hard sell if OSS fits better.