Back to Docs
Chinese Calendar

Chinese Calendar Conversion

GET/api/v1/chinese/calendar/{date}

Convert a Gregorian date to the Chinese lunisolar calendar, zodiac year, Gan-Zhi cycles, solar terms, and festival data. The response exposes both Chinese New Year and Li Chun year boundaries so calendar and BaZi applications can choose the correct convention.

With ?lang=zh-CN, human-readable values and known error messages are localized. JSON keys, stable IDs, error codes, enum values, ISO timestamps, timezone strings, library names, versions, and pinyin remain unchanged for API compatibility.

Full URL

https://api.freeastroapi.com/api/v1/chinese/calendar/{date}

Two year boundaries are intentional

Chinese calendar products commonly change the zodiac year at Lunar New Year. BaZi commonly changes the year pillar at Li Chun. Around early February these may differ, so the API returns both lunar_new_year and li_chun profiles.

Every returned pillar describes one coherent reference instant: civil midnight atUTC+08:00. If a Jie occurs later that day, its exact timestamp and boundary flags appear in solar_terms.current.

Path Parameter

Field
date
Type
string
Required
Yes
Description
Gregorian civil date in YYYY-MM-DD format, for example 2024-02-10.
Field
lang
Type
string
Required
No
Description
Response language. Use zh-CN or zh-Hans for Simplified Chinese; default en.

Required Header

Field
x-api-key
Type
string
Required
Yes
Description
Your FreeAstroAPI key. Requests without a valid key return HTTP 401.

Example Request

curl "https://api.freeastroapi.com/api/v1/chinese/calendar/2024-02-10" \
  -H "x-api-key: YOUR_API_KEY"

Response Fields

Field
gregorian
Type
object
Required
n/a
Description
Input date and weekday in English and Chinese.
Field
lunar
Type
object
Required
n/a
Description
Chinese lunisolar year, month, day, leap-month flag, and Chinese date names.
Field
year_profiles.lunar_new_year
Type
object
Required
n/a
Description
Year Gan-Zhi and zodiac using Chinese New Year as the year boundary.
Field
year_profiles.li_chun
Type
object
Required
n/a
Description
Year Gan-Zhi and zodiac at the declared start-of-day reference instant, using the exact Li Chun boundary.
Field
sexagenary.month
Type
object
Required
n/a
Description
Month pillar at 00:00:00 UTC+08:00. Jie terms change the month at their exact timestamp.
Field
sexagenary.day
Type
object
Required
n/a
Description
Day pillar at the declared civil-midnight reference instant.
Field
solar_terms
Type
object
Required
n/a
Description
Current, previous, and next terms with ISO 8601 UTC+08:00 timestamps, Jie/Qi classification, and BaZi boundary flags.
Field
festivals
Type
object
Required
n/a
Description
Traditional festivals and secondary recurring observances. Secondary observances are explicitly marked as not historically filtered.
Field
metadata
Type
object
Required
n/a
Description
Reference instant, timezone, precision, rollover convention, library provenance, and independently validated range.

Example Response

{
  "gregorian": {
    "date": "2024-02-10",
    "year": 2024,
    "month": 2,
    "day": 10,
    "weekday": "Saturday",
    "weekday_zh": "六"
  },
  "lunar": {
    "year": 2024,
    "month": 1,
    "day": 1,
    "is_leap_month": false,
    "year_name": "二〇二四",
    "month_name": "正月",
    "day_name": "初一"
  },
  "year_profiles": {
    "lunar_new_year": {
      "gan_zhi": "甲辰",
      "gan": "甲",
      "zhi": "辰",
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "chén",
      "stem_element": "Wood",
      "branch_element": "Earth",
      "stem_polarity": "Yang",
      "branch_polarity": "Yang",
      "zodiac": "Dragon",
      "zodiac_zh": "龙"
    },
    "li_chun": {
      "gan_zhi": "甲辰",
      "gan": "甲",
      "zhi": "辰",
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "chén",
      "stem_element": "Wood",
      "branch_element": "Earth",
      "stem_polarity": "Yang",
      "branch_polarity": "Yang",
      "zodiac": "Dragon",
      "zodiac_zh": "龙"
    }
  },
  "sexagenary": {
    "month": {
      "gan_zhi": "丙寅",
      "gan": "丙",
      "zhi": "寅",
      "gan_pinyin": "bǐng",
      "zhi_pinyin": "yín",
      "stem_element": "Fire",
      "branch_element": "Wood",
      "stem_polarity": "Yang",
      "branch_polarity": "Yang"
    },
    "day": {
      "gan_zhi": "甲辰",
      "gan": "甲",
      "zhi": "辰",
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "chén",
      "stem_element": "Wood",
      "branch_element": "Earth",
      "stem_polarity": "Yang",
      "branch_polarity": "Yang"
    }
  },
  "solar_terms": {
    "current": null,
    "previous": {
      "name": "立春",
      "at": "2024-02-04T16:27:07+08:00",
      "timezone": "UTC+08:00",
      "kind": "jie",
      "changes_bazi_month": true,
      "changes_bazi_year": true
    },
    "next": {
      "name": "雨水",
      "at": "2024-02-19T12:13:12+08:00",
      "timezone": "UTC+08:00",
      "kind": "qi",
      "changes_bazi_month": false,
      "changes_bazi_year": false
    }
  },
  "festivals": {
    "solar": [],
    "lunar": ["春节"],
    "other_solar": ["国际气象节"],
    "other_lunar": [],
    "other_observances_historically_filtered": false
  },
  "metadata": {
    "engine_version": "1.3.0",
    "calendar": "chinese_lunisolar",
    "date_only": true,
    "calendar_library": "lunar-python",
    "calendar_library_version": "1.4.8",
    "calculation_standard": "ShouXing astronomical algorithms via lunar-python",
    "reference_timezone": "UTC+08:00",
    "reference_instant": "2024-02-10T00:00:00+08:00",
    "pillar_precision": "start_of_civil_day",
    "day_rollover_convention": "civil_midnight",
    "solar_term_times": "iso_8601_with_fixed_utc_offset",
    "validated_date_range": {
      "start_date": "1901-01-01",
      "end_date": "2100-12-31",
      "authority": "Hong Kong Observatory Gregorian-Lunar conversion tables"
    },
    "within_validated_date_range": true,
    "festival_observance_policy": "other_solar and other_lunar are recurring library labels and are not filtered by historical introduction year"
  }
}

Errors and conventions

  • A missing, invalid, or expired x-api-key returns HTTP 401.
  • An invalid YYYY-MM-DD path value or an impossible ordinary date returns HTTP 422.
  • Dates from 1582-10-05 through 1582-10-14 return HTTP 400 with the structured historical-calendar error shown below.
  • This is a date-only conversion; all pillars describe 00:00:00 at fixed UTC+08:00.
  • Solar-term timestamps are ISO 8601 values with an explicit +08:00 offset.
  • Use each term's Jie/Qi and boundary flags to identify exact BaZi year or month transitions.
  • The independently validated conversion range is 1901-01-01 through 2100-12-31.
  • Secondary observances recur annually and are not filtered by their historical introduction year.
  • Unexpected engine failures return HTTP 500 with code calendar_engine_error.
  • The same valid input date produces the same response and is safe to cache.

401 — Missing API key

{
  "detail": "Missing x-api-key header"
}

400 — Gregorian reform gap

{
  "detail": {
    "code": "gregorian_reform_gap",
    "message": "Dates 1582-10-05 through 1582-10-14 do not exist in the historical Gregorian calendar.",
    "start_date": "1582-10-05",
    "end_date": "1582-10-14"
  }
}

Related Endpoints

BaZi Chart

Calculate a full Four Pillars natal chart.

Current Pillars

Get the Four Pillars for the current moment.