UapiProUApiPro
Misc

Query Lunar Calendar Time

0calls
Free

Need the lunar-calendar information for a specific timestamp in a given time zone? This endpoint returns the full result directly.

GET
uapis.cn
/api/v1/misc/lunartime
Query parameters
2
ts
string

Unix timestamp. Both 10-digit (seconds) and 13-digit (milliseconds) formats are accepted. Defaults to the current time when omitted.

timezone
string

Time-zone name. Accepts IANA time zones (e.g. Asia/Shanghai) and aliases (Shanghai, Beijing). Defaults to Asia/Shanghai.

Overview

Accepts a Unix timestamp (seconds or milliseconds) plus an IANA time-zone name and returns the Gregorian time, weekday, lunar year/month/day, ganzhi (sexagenary cycle), Chinese zodiac, solar terms, and festivals. When ts is omitted the current time is used; when timezone is omitted Asia/Shanghai is used.

Time-zone notes

  • Standard IANA time zones such as Asia/Shanghai and Asia/Tokyo are supported.
  • Aliases such as Shanghai and Beijing are also accepted.
  • An invalid time zone returns 400 with invalid timezone: xxx.

Query parameters

ts
stringoptional

Unix timestamp. Both 10-digit (seconds) and 13-digit (milliseconds) formats are accepted. Defaults to the current time when omitted.

timezone
stringoptional

Time-zone name. Accepts IANA time zones (e.g. Asia/Shanghai) and aliases (Shanghai, Beijing). Defaults to Asia/Shanghai.

Response

200 / OK

Lookup succeeded. Returns the lunar-calendar information for the given time and zone.

JSON
{
  // Original `ts` request value.
  "query_timestamp": "1707537600",
  // Original `timezone` request value.
  "query_timezone": "Asia/Shanghai",
  // Resolved time zone.
  "timezone": "Asia/Shanghai",
  // Localized time, formatted as `YYYY-MM-DD HH:mm:ss`.
  "datetime": "2024-02-10 12:00:00",
  // RFC3339 time format.
  "datetime_rfc3339": "2024-02-10T12:00:00+08:00",
  // Unix timestamp (seconds).
  "timestamp_unix": 1707537600,
  // Weekday (English).
  "weekday": "Saturday",
  // Weekday (Chinese).
  "weekday_cn": "星期六",
  // Lunar year (numeric).
  "lunar_year": 2024,
  // Lunar month (numeric).
  "lunar_month": 1,
  // Lunar day (numeric).
  "lunar_day": 1,
  // Whether the lunar month is a leap month.
  "is_leap_month": false,
  // Lunar year as Chinese characters.
  "lunar_year_cn": "二〇二四",
  // Lunar month as Chinese characters.
  "lunar_month_cn": "正月",
  // Lunar day as Chinese characters.
  "lunar_day_cn": "初一",
  // Ganzhi year.
  "ganzhi_year": "甲辰",
  // Ganzhi month.
  "ganzhi_month": "丙寅",
  // Ganzhi day.
  "ganzhi_day": "甲辰",
  // Chinese zodiac sign.
  "zodiac": "龙",
  // Solar-term name. Returned when one applies; otherwise an empty string or omitted.
  "solar_term": "",
  // Array of lunar-calendar festivals.
  "lunar_festivals": [
    "春节"
  ],
  // Array of Gregorian-calendar festivals.
  "solar_festivals": [
    "元旦"
  ]
}

400 / Bad Request

Invalid request. An invalid timezone returns invalid timezone: xxx; an invalid ts returns invalid timestamp: xxx.

JSON
{
  "code": 400,
  "message": "invalid timezone: xxx"
}
PreviousQuery World Time
NextHoliday and Calendar Lookup