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

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

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 4, 2025):

New Year:        Jan 1-3 (3 days off), Jan 4 (Sun) = workday
Spring Festival: Feb 15-23 (9 days off), Feb 14 (Sat) & Feb 28 (Sat) = workdays
Labor Day:       May 1-5 (5 days off), May 9 (Sat) = workday
National Day:    Oct 1-7 (7 days off), Sep 20 (Sun) & Oct 10 (Sat) = workdays

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

// Correct response should be:
{"date": "2026-02-14", "weekday": "Saturday", "type": "adjusted_workday", "is_workday": true}

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

No staff scheduled on adjusted workdays → uncovered shifts
Attendance system marks employees as absent on workdays
Order ETA miscalculated by a day
Cron jobs fire (or don't fire) incorrectly

The Solution

I built Global Holidays API — on RapidAPI, covering 501 countries/regions, with China's adjusted workdays as exclusive data.

Data source: Official State Council annual notices, manually maintained, accurate to every single day.

Key Features

Feature	Description	Other APIs
China adjusted workdays	Weekend make-up work days return `is_workday: true`	❌ Exclusive
Workday checking	One call to check if a date is a workday (with adjusted workday logic)	Partial
501 countries	Based on python-holidays open-source library	Similar
US state-level holidays	57 subdivisions with state-specific holidays	Paid only
Date range analysis	Input start/end dates, get workday/holiday/weekend counts	Rare
Next holiday finder	Find the next public holiday for any country	Rare

Usage (Python)

import requests

# Your RapidAPI API Key
API_KEY = "your_rapidapi_key"
headers = {
    "X-RapidAPI-Key": API_KEY,
    "X-RapidAPI-Host": "global-holidays-api3.p.rapidapi.com"
}

# 1. Check if 2026-02-14 is a workday
resp = requests.get(
    "https://global-holidays-api3.p.rapidapi.com/is-workday/CN/2026-02-14",
    headers=headers
)
print(resp.json())
# {"date": "2026-02-14", "weekday": "Saturday", "type": "adjusted_workday",
#  "name": "调休补班", "is_workday": true, "source": "china_override"}

# 2. Get all China adjusted workdays for 2026
resp = requests.get(
    "https://global-holidays-api3.p.rapidapi.com/china/adjusted-workdays/2026",
    headers=headers
)
print(resp.json())
# {"count": 6, "adjusted_workdays": [
#   {"date": "2026-01-04", "name": "调休补班", "weekday": "Sunday"},
#   {"date": "2026-02-14", "name": "调休补班", "weekday": "Saturday"},
#   {"date": "2026-02-28", "name": "调休补班", "weekday": "Saturday"},
#   {"date": "2026-05-09", "name": "调休补班", "weekday": "Saturday"},
#   {"date": "2026-09-20", "name": "调休补班", "weekday": "Sunday"},
#   {"date": "2026-10-10", "name": "调休补班", "weekday": "Saturday"},
# ]}

# 3. Count workdays in a date range
resp = requests.get(
    "https://global-holidays-api3.p.rapidapi.com/date-range/CN",
    headers=headers,
    params={"start": "2026-02-12", "end": "2026-02-17"}
)
print(resp.json()["workdays"])  # 2

Usage (cURL)

# Check if 2026-02-14 is a workday
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"

# Get California state holidays (includes Cesar Chavez Day, Diwali, etc.)
curl "https://global-holidays-api3.p.rapidapi.com/holidays/US/2026?subdiv=CA" \
  -H "X-RapidAPI-Key: your_key" \
  -H "X-RapidAPI-Host: global-holidays-api3.p.rapidapi.com"

Real-World Scenarios

Scenario 1: Attendance System

# Check if employees need to clock in today
result = client.is_workday("CN", "2026-02-14")
if result["is_workday"]:
    # It's a workday — enable clock-in
    pass
else:
    # It's a holiday
    pass

Scenario 2: Order ETA Calculation

# Count actual workdays between two dates
result = client.date_range("CN", start="2026-02-12", end="2026-02-18")
workdays = result["workdays"]  # Get actual workday count
# Use for order delivery estimate

Scenario 3: Skip Cron Jobs on Holidays

# Run daily at 9am, but skip on holidays
result = client.is_workday("CN", "2026-02-16")
if not result["is_workday"]:
    continue  # It's a holiday — skip
do_daily_task()

Comparison with Competitors

	This API	Calendarific	HolidayAPI.com	Abstract API
Countries	501	230+	250	190+
China adjusted workdays	✅ Exclusive	❌	❌	❌
US state-level	✅ Free	Paid	$399/yr	Paid
Workday checking	✅	❌	❌	Partial
Date range analysis	✅	❌	❌	❌
Free tier	1,000/mo	500/mo	1,000/mo	1,000/mo
Cheapest paid	$10/mo	$8.3/mo	$20.75/mo	$99/mo

Pricing

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

Free tier works without a credit card.

Get Started

Visit Global Holidays API on RapidAPI
Subscribe to the Free plan (1,000 requests/month, no credit card)
Get your API key
Start coding with the examples above

Found this useful? Give it a ⭐ on RapidAPI! Found a data error? Submit feedback directly on the API docs page — I'll fix it ASAP.

🔗 https://rapidapi.com/cdd3544/api/global-holidays-api3

DEV Community: alex