Misc

Holiday and Calendar Lookup

0calls

1 credits / call

Look up calendar and holiday information for a specific day, month, or year.

Overview

The endpoint supports three query modes: by day (date), by month (month), and by year (year). Pick exactly one of these per call.

Use holiday_type to filter to a single category — for example legal holidays / make-up workdays, Gregorian festivals, lunar-calendar festivals, or solar terms.

In date mode, pass include_nearby=true to also return the holidays nearest the queried date. Use nearby_limit to cap the number of returned items (default 7, max 30).

If you only want today and future holidays, pass exclude_past=true to drop past entries.

Query parameters

date

stringoptional

Use this when querying by day. Format: YYYY-MM-DD. Choose exactly one of date, month, year.

month

stringoptional

Use this when querying by month. Format: YYYY-MM. Choose exactly one of date, month, year.

year

stringoptional

Use this when querying by year. Format: YYYY. Choose exactly one of date, month, year.

timezone

stringoptional

Time-zone name. Defaults to Asia/Shanghai.

holiday_type

stringoptional

Holiday-type filter. Defaults to all.

include_nearby

booleanoptional

Whether to also return the nearest holidays before and after the queried date. Only meaningful in date mode; ignored in month/year mode. Defaults to false.

nearby_limit

integeroptional

Maximum number of nearest holidays to return. Default 7, max 30. Only applies in date mode with include_nearby=true.

exclude_past

booleanoptional

When true, filters out holidays that have already passed before today. Defaults to false.

Name	Type	Attributes	Description
`date`	string	optional	Use this when querying by day. Format: `YYYY-MM-DD`. Choose exactly one of `date`, `month`, `year`.
`month`	string	optional	Use this when querying by month. Format: `YYYY-MM`. Choose exactly one of `date`, `month`, `year`.
`year`	string	optional	Use this when querying by year. Format: `YYYY`. Choose exactly one of `date`, `month`, `year`.
`timezone`	string	optional	Time-zone name. Defaults to `Asia/Shanghai`.
`holiday_type`	string	optional	Holiday-type filter. Defaults to `all`.
`include_nearby`	boolean	optional	Whether to also return the nearest holidays before and after the queried date. Only meaningful in `date` mode; ignored in `month`/`year` mode. Defaults to `false`.
`nearby_limit`	integer	optional	Maximum number of nearest holidays to return. Default 7, max 30. Only applies in `date` mode with `include_nearby=true`.
`exclude_past`	boolean	optional	When `true`, filters out holidays that have already passed before today. Defaults to `false`.

Response

200 / OK

Lookup succeeded. Returns calendar and holiday information for the requested range.

JSON

400 / Bad Request

Invalid request. Common causes:

None of date/month/year provided, or more than one provided.
Wrong date format: date must be YYYY-MM-DD, month must be YYYY-MM, year must be YYYY.
Invalid holiday_type.
Invalid timezone.

JSON

Quick start

Pick your language to see usage examples

Auth mode:

cURL command

curl 'https://uapis.cn/api/v1/misc/holiday-calendar'

Frequently asked questions

Are there any special restrictions for the Holiday and Calendar Lookup API?

Holiday and Calendar Lookup follows our standard usage policy. Refer to the endpoint reference above for the exact rate limits and parameter requirements. Reach out if you have unusual needs.

Are the APIs on UAPI free to use?

UAPI gives every visitor free credits so you can call any endpoint right away. Visitor credits have a usage cap, and if you need more you can for additional credits.

Do I need to register an account to use UAPI?

No registration is required for visitor credit calls. If you need more credits or want to manage your call history, you can register a free account. Signed-in users get more free credits and can review usage details in the console.

Which languages and use cases does UAPI support?

Our APIs follow standard HTTP and RESTful design, so any language that can send network requests works — including JavaScript (Node.js, Vue, React), Python, Java, PHP, Go, C#, and more. They fit web apps, mobile backends, mini-program cloud functions, automation scripts, and similar scenarios.