---
title: "Convert Gregorian Date to Chinese Calendar"
method: GET
path: "/api/v1/chinese/calendar/{date}"
tags: ["Chinese", "chinese"]
---

# Convert Gregorian Date to Chinese Calendar

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

## Request

- Base URL: `https://api.freeastroapi.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.freeastroapi.com/api/v1/chinese/calendar/{date}`
- Auth: none declared. Required headers: `x-api-key`

Convert a Gregorian date to Chinese lunisolar calendar data.
Returns lunar date names, lunar-new-year and Li Chun year profiles,
sexagenary month/day cycles, solar terms, and festivals.

## Path parameters

- `date` string, date, required

## Query parameters

- `lang` string: Response language. Supported: en, zh-Hans, zh-CN, zh_hans.

## Headers

- `x-api-key` string, required

## Response `200`

Successful Response

- ChineseCalendarResponse
  - `gregorian` ChineseCalendarGregorianDate, required
    - `date` string, required
    - `year` integer, required
    - `month` integer, required
    - `day` integer, required
    - `weekday` string, required
    - `weekday_zh` string, required
  - `lunar` ChineseCalendarLunarDate, required
    - `year` integer, required
    - `month` integer, required
    - `day` integer, required
    - `is_leap_month` boolean, required
    - `year_name` string, required
    - `month_name` string, required
    - `day_name` string, required
  - `year_profiles` ChineseCalendarYearProfiles, required
    - `lunar_new_year` ChineseCalendarYearProfile, required
      - `gan_zhi` string, required
      - `gan` string, required
      - `zhi` string, required
      - `gan_pinyin` string, required
      - `zhi_pinyin` string, required
      - `stem_element` string, required
      - `branch_element` string, required
      - `stem_polarity` string, required
      - `branch_polarity` string, required
      - `zodiac` string, required
      - `zodiac_zh` string, required
    - `li_chun` ChineseCalendarYearProfile, required
      - `gan_zhi` string, required
      - `gan` string, required
      - `zhi` string, required
      - `gan_pinyin` string, required
      - `zhi_pinyin` string, required
      - `stem_element` string, required
      - `branch_element` string, required
      - `stem_polarity` string, required
      - `branch_polarity` string, required
      - `zodiac` string, required
      - `zodiac_zh` string, required
  - `sexagenary` ChineseCalendarSexagenary, required
    - `month` ChineseCalendarCycle, required
      - `gan_zhi` string, required
      - `gan` string, required
      - `zhi` string, required
      - `gan_pinyin` string, required
      - `zhi_pinyin` string, required
      - `stem_element` string, required
      - `branch_element` string, required
      - `stem_polarity` string, required
      - `branch_polarity` string, required
    - `day` ChineseCalendarCycle, required
      - `gan_zhi` string, required
      - `gan` string, required
      - `zhi` string, required
      - `gan_pinyin` string, required
      - `zhi_pinyin` string, required
      - `stem_element` string, required
      - `branch_element` string, required
      - `stem_polarity` string, required
      - `branch_polarity` string, required
  - `solar_terms` ChineseCalendarSolarTerms, required
    - `current` ChineseCalendarSolarTerm, required
      - `name` string, required
      - `at` string, required
      - `timezone` 'UTC+08:00', required
      - `kind` 'jie' | 'qi', required
      - `changes_bazi_month` boolean, required
      - `changes_bazi_year` boolean, required
    - `previous` ChineseCalendarSolarTerm, required
      - `name` string, required
      - `at` string, required
      - `timezone` 'UTC+08:00', required
      - `kind` 'jie' | 'qi', required
      - `changes_bazi_month` boolean, required
      - `changes_bazi_year` boolean, required
    - `next` ChineseCalendarSolarTerm, required
      - `name` string, required
      - `at` string, required
      - `timezone` 'UTC+08:00', required
      - `kind` 'jie' | 'qi', required
      - `changes_bazi_month` boolean, required
      - `changes_bazi_year` boolean, required
  - `festivals` ChineseCalendarFestivals, required
    - `solar` string[], required
    - `lunar` string[], required
    - `other_solar` string[], required
    - `other_lunar` string[], required
    - `other_observances_historically_filtered` boolean, required
  - `metadata` ChineseCalendarMetadata, required
    - `engine_version` string, required
    - `calendar` string, required
    - `date_only` boolean, required
    - `calendar_library` 'lunar-python', required
    - `calendar_library_version` string, required
    - `calculation_standard` string, required
    - `reference_timezone` 'UTC+08:00', required
    - `reference_instant` string, required
    - `pillar_precision` 'start_of_civil_day', required
    - `day_rollover_convention` 'civil_midnight', required
    - `solar_term_times` 'iso_8601_with_fixed_utc_offset', required
    - `validated_date_range` ChineseCalendarValidatedRange, required
      - `start_date` string, required
      - `end_date` string, required
      - `authority` string, required
    - `within_validated_date_range` boolean, required
    - `festival_observance_policy` string, required

## Other responses

- `400`: The date falls inside the historical Gregorian reform gap.
- `401`: The x-api-key header is missing or invalid.
- `422`: Validation Error
- `500`: The calendar engine could not complete the conversion.

---

[API](https://skmtc.dev/freeastroapi/apis/astroservice-api.md) · [All operations](https://skmtc.dev/freeastroapi/apis/astroservice-api/llms.txt) · [OpenAPI document](https://skmtc.dev/freeastroapi/apis/astroservice-api/revisions/0c9b4a759522?raw)