China Workday & Holiday Calendar API (调休, Lunar, Solar Terms)

Is this date a working day in mainland China? Weekends are not enough: China moves working days onto Saturdays and Sundays (调休 / make-up workdays) around every major holiday, and the schedule changes every year. This Actor answers that question from the official State Council notices, and adds the lunar date, the 24 solar terms and business-day arithmetic, all in one call.

• ✅ Official schedules typed from the State Council notices for 2024, 2025 and 2026, with the source URL on every row
• ✅ Make-up working days (adjusted_workday), holiday periods, and the legally defined statutory holidays (法定节假日, the days that carry triple pay)
• ✅ addWorkdays / countWorkdays for SLAs, delivery dates, payroll and settlement cycles
• ✅ Lunar date (农历), ganzhi year and zodiac, plus all 24 solar terms (节气) with exact Beijing time
• ✅ Honest about uncertainty: years whose schedule is not published yet are marked "dataStatus": "estimated"
• ⚡ No scraping, no proxy, no external calls at run time; runs finish in about a second on 256 MB

Who uses it

• AI agents and MCP clients that need "is it a working day in China?" or "what date is 10 working days after X?"
• Logistics, cross-border e-commerce and supplier management: factory closures, ETA and lead-time calculation around Chinese New Year and Golden Week
• Finance and payroll: settlement days, statutory holiday pay
• Marketing and content calendars: lunar festivals and solar terms

Operations

operation	Input	Output (one row each)
check (default)	dates: list of YYYY-MM-DD (max 1000)	one row per date
range	startDate, endDate, optional maxDays (default 366, max 3660)	one row per day
addWorkdays	startDate, days (−2000…2000)	1 row with resultDate
countWorkdays	startDate, endDate (inclusive)	1 row with counts
holidays	year	one row per holiday period
solarTerms	year	24 rows

includeLunar (default true) adds the lunar block to day rows.

Example: check dates

Input:

{ "operation": "check", "dates": ["2026-10-01", "2026-10-10", "2027-02-06"] }

Output (second row):

{
  "date": "2026-10-10",
  "weekday": 6,
  "weekdayName": "Saturday",
  "isWorkday": true,
  "dayType": "adjusted_workday",
  "holidayName": null,
  "holidayNameZh": null,
  "isStatutoryHoliday": false,
  "solarTerm": null,
  "dataStatus": "official",
  "sourceUrl": "https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm",
  "lunar": { "year": 2026, "month": 9, "day": 1, "isLeapMonth": false, "text": "九月初一", "ganzhiYear": "丙午", "zodiac": "马" }
}

dayType is one of workday, weekend, holiday, adjusted_workday. isWorkday is true for workday and adjusted_workday.

Example: add working days

{ "operation": "addWorkdays", "startDate": "2026-09-30", "days": 10 }

{ "operation": "addWorkdays", "startDate": "2026-09-30", "days": 10, "resultDate": "2026-10-20", "resultWeekdayName": "Tuesday", "dataStatus": "official" }

days: 0 returns startDate if it is a working day, otherwise the next working day. Negative values count backwards.

Example: count working days

{ "operation": "countWorkdays", "startDate": "2026-01-01", "endDate": "2026-12-31" }

{ "operation": "countWorkdays", "startDate": "2026-01-01", "endDate": "2026-12-31", "calendarDays": 365, "workdays": 248, "adjustedWorkdays": 6, "weekendDays": 84, "holidayDays": 33, "dataStatus": "official" }

Example: holiday periods

{ "operation": "holidays", "year": 2026 }

{ "year": 2026, "name": "Spring Festival", "nameZh": "春节", "startDate": "2026-02-15", "endDate": "2026-02-23", "daysOff": 9, "adjustedWorkdays": ["2026-02-14", "2026-02-28"], "dataStatus": "official", "notice": "国办发明电〔2025〕7号", "sourceUrl": "https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm" }

Example: solar terms

{ "operation": "solarTerms", "year": 2026 }

{ "year": 2026, "name": "Cold Dew", "nameZh": "寒露", "date": "2026-10-08", "datetimeBeijing": "2026-10-08T14:29:17+08:00", "datetimeUtc": "2026-10-08T06:29:17+00:00" }

Data sources and accuracy

• Holiday and make-up workday schedules: annual notices of the General Office of the State Council (国务院办公厅关于部分节假日安排的通知) on www.gov.cn. Each row carries the notice URL.
  • 2024: 国办发明电〔2023〕7号, 2025: 国办发明电〔2024〕12号, 2026: 国办发明电〔2025〕7号
• Statutory holiday definition: the National Measures on Holidays as amended by State Council Decree No. 795 (effective 2025-01-01): 13 days from 2025 (11 days before).
• Every day of 2024–2026 is cross-checked in the test suite against an independent open-source dataset.
• Years without a published schedule (for example 2027, until the State Council publishes it, usually in late October or November): statutory holidays and weekends only. Bridge days and make-up workdays are unknown, so rows are flagged "dataStatus": "estimated". The Actor is updated after each new notice.
• Lunar dates and solar terms are computed astronomically (Beijing time, UTC+8).
• Mainland China only. Hong Kong, Macau and Taiwan have different holidays.

Pricing

Pay per event:

• Actor start: charged once per run
• Result: per row in the dataset (one per date for check and range, one per calculation, one per holiday period or solar term)

Set a maximum charge per run and the Actor stops cleanly at the limit. Invalid input fails immediately and produces no results.

Use from an AI agent (MCP)

The Actor has a single clear purpose and a typed input schema, so MCP clients can call it directly through the Apify MCP server. Typical prompts: "Is 2026-10-10 a working day in China?", "Add 15 Chinese working days to 2026-09-25".

Limits

• check: 1000 dates per run. range: up to 3660 days. addWorkdays: ±2000 working days. Years 1950–2099.
• This is a reference tool, not legal advice. Local governments and individual employers can set extra rules.

Changelog

• 0.1: first release. Official schedules for 2024–2026, lunar calendar, solar terms, add/count working days.