Skip to content
ZGI Services

Public holidays

Classify every date of a range (up to 93 days) in one region as workday, weekend, public holiday, or adjusted workday (a weekend date worked to compensate for a holiday). Use holiday-cn for mainland China (includes adjusted workdays), gov-uk for GB, nager for other countries.
Endpoint POST /v1/public-holiday-queries
Scope public_holiday:query
MCP tool public_holiday
Usage units days

Usage units appear in execution.usage.units for reconciliation and billing.

Request fields

Section titled “Request fields”
Field Type Required Description
invocation_id string yes The market’s invocation id: one execution per id and operation, so a retry with the same id is rejected instead of charged twice. 1-128 characters of A-Z a-z 0-9 . _ : -.
provider string yes Provider that serves the request; choose by the coverage described for this tool. One of: gov-uk, holiday-cn
end_date string yes Last date, YYYY-MM-DD, inclusive; at most 93 days after start_date.
region string yes ISO 3166-1 alpha-2 region code, for example CN, GB, DE or US.
start_date string yes First date, YYYY-MM-DD.

Providers

Section titled “Providers”
Provider Region Source Limits
gov-uk GB GOV.UK bank holidays first_year: 2025, last_year: 2028, max_range_days: 93, timeout_seconds: 30
holiday-cn CN State Council holiday announcements, with adjusted workdays first_year: 2020, last_year: 2026, max_range_days: 93, timeout_seconds: 30

Example

Section titled “Example”
终端窗口
curl -sS https://services.zgi.im/v1/public-holiday-queries \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"invocation_id": "docs-1791778521-public_holiday", "provider": "holiday-cn", "region": "CN", "start_date": "2026-10-01", "end_date": "2026-10-08"}'

Response

Section titled “Response”

A real response, with lists cut to two items and long text shortened.

{
  "code": 0,
  "message": "success",
  "data": {
    "execution": {
      "id": "exe_01a12e52b912717faddb9b0372c2d034",
      "invocation_id": "docs-1791778521-public_holiday",
      "capability": "public_holiday",
      "operation": "public_holiday.query",
      "provider": "holiday-cn",
      "outcome": "succeeded",
      "error_category": null,
      "error_code": null,
      "usage": {
        "provider_requests": 0,
        "units": [
          {
            "name": "days",
            "value": 8,
            "source": "measured"
          }
        ]
      },
      "upstream_ref": null,
      "request_id": "req_f6d2d539aa9170eb053725a6",
      "started_at": "2026-10-12T04:15:35.698094679Z",
      "finished_at": "2026-10-12T04:15:35.705615992Z",
      "duration_ms": 7
    },
    "result": {
      "region": "CN",
      "start_date": "2026-10-01",
      "end_date": "2026-10-08",
      "days": [
        {
          "date": "2026-10-01",
          "weekday": 4,
          "day_type": "public_holiday",
          "is_off_day": true,
          "holiday_name": "国庆节"
        },
        {
          "date": "2026-10-02",
          "weekday": 5,
          "day_type": "public_holiday",
          "is_off_day": true,
          "holiday_name": "国庆节"
        }
      ],
      "totals": {
        "workdays": 1,
        "off_days": 7
      },
      "source": {
        "name": "holiday-cn (State Council announcements)",
        "license": "MIT",
        "announcements": [
          "https://www.gov.cn/zhengce/zhengceku/202511/content_7047091.htm"
        ]
      }
    }
  }
}