DEV Community: alex

How to Calculate Business Days in China (调休 Explained) — Without Losing Your Mind

alex — Fri, 04 Sep 2026 08:45:54 +0000

How to Calculate Business Days in China (调休 Explained) — Without Losing Your Mind

If you've ever built software that touches China — payroll, invoicing, delivery estimates, SLA timers, interest calculations — you've probably hit this problem:

China moves workdays to weekends.

And almost every holiday API gets this wrong.

The 调休 Problem

Let me show you a real example. Here's February 2026 in China:

Feb 14 is a Saturday. A normal calendar says: weekend.
The Chinese government says: it's a workday.

Why? Spring Festival 2026 runs Feb 15–23 (9 days off). To "pay back" those extra days, the State Council schedules make-up workdays (调休补班) on surrounding weekends — Feb 14 being one of them.

This isn't an edge case. In 2026, there are 6 such days. Every year has 4–8 of them.

What this breaks

Task	Naive calculation	Reality
Payroll for Feb 2026	20 workdays	16 workdays
"Invoice due in 3 business days" from Sep 30	Oct 10 is a Saturday → due Oct 13	Due Oct 10 (it's a make-up workday)
Interest accrual for 2026	~261 days	248 days

If you compute any of these wrong, you either underpay staff, miss contractual deadlines, or misbill customers.

Why Most APIs Get This Wrong

I checked the major holiday APIs while building Global Holidays & Business Days API. Almost all of them — including the big names — return Chinese holidays but treat every Saturday/Sunday as a non-workday. The make-up workdays simply don't exist in their data.

Why? Because the data source most of them use (open-source holiday libraries) encodes holidays — but 调休 make-up days aren't holidays. They're the opposite: workdays disguised as weekends. They only exist in the State Council's annual notice (国务院办公厅通知), published every November.

The Fix

This is exactly why I built the Business Days API — it layers the official State Council data on top of 500+ countries of holiday data. Every workday-related endpoint applies the full 调休 logic automatically.

Example 1: Count business days in a date range

curl "https://lingcode.me/business-days-between/CN?start=2026-01-01&end=2026-12-31"

{
  "calendar_days": 365,
  "business_days": 248,
  "holidays": 33,
  "weekends": 84,
  "adjusted_workdays_included": 6,
  "note": "含中国调休补班逻辑（国务院办公厅通知）"
}

248 — not 261. The 6 make-up days are correctly counted as workdays, and the holidays that fall on weekdays are correctly excluded.

Example 2: The invoice due date problem

"Due in 3 business days, starting Sep 30, 2026." Golden Week starts Oct 1. Naive logic says Oct 13 (first Tuesday after the holiday + weekend). The API says:

curl "https://lingcode.me/next-business-day/CN?d=2026-09-30&offset=3"

{
  "from_date": "2026-09-30",
  "next_business_day": "2026-10-10",
  "weekday": "周六",
  "name": "调休补班",
  "calendar_days_taken": 10
}

Oct 10 — a Saturday that is actually a workday. The API even tells you why (name: 调休补班).

Example 3: Monthly payroll report

curl "https://lingcode.me/business-days-in-month/CN/2026/2"

{
  "business_days": 16,
  "holidays": 9,
  "weekends": 3,
  "adjusted_workdays_included": 2,
  "business_day_list": ["2026-02-02", "...", "2026-02-14", "..."]
}

A full workday date list for HR systems — note Feb 14 in there.

It's Not Just China

The same API covers 500+ countries with state/province-level subdivisions (US: 57 subdivisions). So your business-days-between for US correctly handles Thanksgiving, JP handles Golden Week, DE handles Unity Day — all with the same interface:

curl "https://lingcode.me/business-days-between/US?start=2026-11-20&end=2026-12-31"
# → business_days: 27 (correctly skips Thanksgiving + Christmas)

Use Cases Where This Matters

Payroll & contractors — Chinese staff work (and get paid for) make-up Saturdays
Invoicing & billing — due dates that legally roll past holidays
Delivery SLAs — logistics timelines across Golden Week
Interest calculation — day-count conventions for loans involving Chinese entities
Project management — realistic sprint planning with Chinese teams

Try It

Docs & live demo: lingcode.me
RapidAPI: Global Holidays & Business Days API (free tier: 300 requests/month)
Data methodology: How we source 调休 data from State Council notices

The 2026 dataset is complete. The 2027 dataset ships within 24 hours of the State Council's announcement (expected November 2026).

Found this useful? The API also does is-workday checks, next-holiday lookups, and full date-range analysis — all with the same 调休-aware logic. Feedback welcome via the feedback form.

Every Holiday API Gets China Wrong - Here's How I Fixed It

alex — Tue, 11 Aug 2026 01:32:57 +0000

\n*This post was updated on Sep 4, 2026 — the API now has dedicated Business Days endpoints (workday counting, next-business-day, monthly stats). Scroll to "What's New" below.*

Before every Chinese New Year, backend developer groups see the same question:

"Is February 14th a workday or not?"

The answer: Yes, it's a workday. It's a "调休补班" — a Saturday, but you have to go to the office.

The Problem

Mainstream holiday APIs (Calendarific, HolidayAPI.com, Abstract API, Nager.Date) all cover 200+ countries' public holidays. But they share one blind spot when it comes to China:

They only return official holidays. They don't handle adjusted workdays (调休补班).

China's 2026 holiday schedule (source: State Council notice, Nov 2025):

Holiday	Days off	Make-up workdays
New Year	Jan 1–3 (3 days)	Jan 4 (Sun)
Spring Festival	Feb 15–23 (9 days)	Feb 14 (Sat) & Feb 28 (Sat)
Labor Day	May 1–5 (5 days)	May 9 (Sat)
National Day	Oct 1–7 (7 days)	Sep 20 (Sun) & Oct 10 (Sat)

That means 2026 has 6 weekend days where you must go to work. If you query 2026-02-14 with any mainstream API:

// Other APIs return:
{ "date": "2026-02-14", "weekday": "Saturday", "type": "weekend" }
// ❌ Wrong! This is an adjusted workday — you have to work

// This API returns:
{ "date": "2026-02-14", "weekday": "Saturday", "type": "adjusted_workday", "is_workday": true }

If your app involves scheduling, attendance, order ETA, or cron logic — this error causes:

❌ No staff scheduled on adjusted workdays → uncovered shifts
❌ Attendance system marks employees "absent" on actual workdays
❌ Order ETAs off by a day
❌ Cron jobs fire (or don't) incorrectly

The Solution

I built the Business Days & Holidays API — 501 countries/regions, with China's adjusted workdays as exclusive data, sourced from official State Council notices and hand-verified.

🆕 What's New: Business Days Endpoints

Since the original post, I've added three endpoints purpose-built for the "count workdays" jobs this API's users kept asking about:

Endpoint	What it does	Typical use
`GET /business-days-between/{country}`	Count workdays between two dates	Payroll cycles, interest days, SLA
`GET /next-business-day/{country}`	The Nth workday after a date	Invoice due dates, T+N settlement
`GET /business-days-in-month/{country}`	Monthly workday stats + full date list	HR scheduling, payroll reports

Example — "invoice due in 3 business days" starting Sep 30, 2026 (Golden Week starts Oct 1):

{
  "from_date": "2026-09-30",
  "next_business_day": "2026-10-10",
  "weekday": "Saturday",
  "name": "调休补班",
  "calendar_days_taken": 10
}

Oct 10 — a Saturday that is actually a workday. The API tells you why ("name": "调休补班").

Example — full-year workday count for 2026:

{
  "calendar_days": 365,
  "business_days": 248,
  "holidays": 33,
  "weekends": 84,
  "adjusted_workdays_included": 6
}

248, not the naive ~261 — make-up days counted in, weekday holidays counted out.

Quick Start

cURL

curl "https://global-holidays-api3.p.rapidapi.com/is-workday/CN/2026-02-14" \
  -H "X-RapidAPI-Key: YOUR_KEY" \
  -H "X-RapidAPI-Host: global-holidays-api3.p.rapidapi.com"

Python

import requests

headers = {
    "X-RapidAPI-Key": "YOUR_KEY",
    "X-RapidAPI-Host": "global-holidays-api3.p.rapidapi.com",
}
BASE = "https://global-holidays-api3.p.rapidapi.com"

# 1. Is Feb 14 a workday?
requests.get(f"{BASE}/is-workday/CN/2026-02-14", headers=headers).json()
# → {"type": "adjusted_workday", "is_workday": true, "name": "调休补班"}

# 2. All China make-up workdays in 2026
requests.get(f"{BASE}/china/adjusted-workdays/2026", headers=headers).json()
# → 6 dates: Jan 4, Feb 14, Feb 28, May 9, Sep 20, Oct 10

# 3. Workdays between two dates (payroll cycle)
requests.get(f"{BASE}/business-days-between/CN",
             headers=headers,
             params={"start": "2026-02-01", "end": "2026-02-28"}).json()
# → {"business_days": 16, "holidays": 9, "weekends": 3, "adjusted_workdays_included": 2}

Real-World Scenarios

1. Attendance system — enable clock-in only on real workdays:

result = client.is_workday("CN", "2026-02-14")
if result["is_workday"]:
    enable_clock_in()

2. Order ETA — count actual workdays, not calendar days:

result = client.business_days_between("CN", start="2026-02-12", end="2026-02-18")
# → workdays: 2 (Spring Festival week!)

3. Cron jobs — skip holidays, run on make-up workdays:

if not client.is_workday("CN", "2026-02-16")["is_workday"]:
    skip()  # It's a holiday

4. Invoice due dates — "due in 3 business days" done right:

result = client.next_business_day("CN", d="2026-09-30", offset=3)
# → "2026-10-10" (a Saturday make-up workday, correctly)

How It Compares

	This API	Calendarific	HolidayAPI.com	Abstract API
Countries	501	230+	250	190+
China adjusted workdays	✅ exclusive	❌	❌	❌
Business days counting	✅	❌	❌	❌
Next business day	✅	❌	❌	❌
US state-level	✅ free	paid	$399/yr	paid
Free tier	1,000/mo	500/mo	1,000/mo	1,000/mo

Pricing

Plan	Price	Quota
Basic	Free	1,000 requests/mo
Pro ⭐	$10/mo	10,000 requests/mo
Ultra	$25/mo	50,000 requests/mo
Mega	$100/mo	500,000 requests/mo

No credit card needed for the free tier.

DEV Community: alex

How to Calculate Business Days in China (调休 Explained) — Without Losing Your Mind

How to Calculate Business Days in China (调休 Explained) — Without Losing Your Mind

The 调休 Problem

What this breaks

Why Most APIs Get This Wrong

The Fix

Example 1: Count business days in a date range

Example 2: The invoice due date problem

Example 3: Monthly payroll report

It's Not Just China

Use Cases Where This Matters

Try It

Every Holiday API Gets China Wrong - Here's How I Fixed It

The Problem

The Solution

🆕 What's New: Business Days Endpoints

Quick Start

cURL

Python

Real-World Scenarios

How It Compares

Pricing

Links