{"success":true,"version":"v1","request":{"tool":"get_calculator_schema","calculator_id":"lunar-age"},"result":{"entity_type":"calculator","id":"lunar-age","calculator_id":"lunar-age","canonical_url":"https://tttkmbb.com/lunar/lunar-age","name":"Chinese Nominal Age Calculator (虚岁)","title":"Chinese Nominal Age Calculator – Xusui (虚岁) vs Zhousui (周岁), Lunar Birthday and Next 本命年","category":"lunar","category_name":"Chinese Calendar","tool_name":"calculate_chinese_nominal_age","featured_mcp_tool":false,"description":"Computes the traditional Chinese nominal age (虚岁 xusui: one at birth, plus one at every Chinese New Year) alongside the completed-years age (周岁 zhousui), and finds the lunar birthday (农历生日), its Gregorian date in the current lunar year, the days to the next lunar birthday and the next 本命年.","use_when":"You need someone's 虚岁 for a Chinese context (family, temple, almanac conventions), or the date of a lunar birthday in a given year.","do_not_use_when":"You need the ordinary age in years, months and days (use age), or the zodiac sign details (use chinese-zodiac).","inputs":[{"name":"birth_date","label":"Birth date","type":"date","required":true,"description":"Gregorian birth date (civil date in China Standard Time), 1900–2100.","example":"1990-05-17"},{"name":"reference_date","label":"As of","type":"date","required":false,"default":"today","description":"Date on which to evaluate the ages; defaults to the current UTC date.","example":"2026-09-24"}],"outputs":[{"name":"nominal_age_xusui","label":"虚岁 (nominal age)","type":"integer","unit":"sui","decimals":0,"description":"1 at birth plus 1 for every Chinese New Year passed."},{"name":"actual_age_zhousui","label":"周岁 (completed years)","type":"integer","unit":"years","decimals":0,"description":"Completed years since the Gregorian birthday."},{"name":"lunar_birth_date","label":"Lunar birth date","type":"string","decimals":4,"description":"Birth date in the lunar calendar, e.g. 一九九〇年四月廿三."},{"name":"lunar_birthday","label":"Lunar birthday","type":"string","decimals":4,"description":"Lunar month and day of birth, e.g. 四月廿三 (4th lunar month, day 23)."},{"name":"lunar_birthday_this_year","label":"Lunar birthday this lunar year","type":"date","decimals":4,"description":"Gregorian date of the lunar birthday in the lunar year that contains reference_date (regular-month or day-29 fallback noted when needed)."},{"name":"next_lunar_birthday","label":"Next lunar birthday","type":"date","decimals":4,"description":"Gregorian date of the next lunar birthday on or after reference_date."},{"name":"days_to_next_lunar_birthday","label":"Days to next lunar birthday","type":"integer","unit":"days","decimals":0,"description":"0 when reference_date is the lunar birthday."},{"name":"current_lunar_year","label":"Current lunar year","type":"string","decimals":4,"description":"Lunar year containing reference_date with its ganzhi and animal."},{"name":"is_benmingnian_now","label":"本命年 now","type":"boolean","decimals":4,"description":"true when the current lunar year has the birth-year animal."},{"name":"next_benmingnian_year","label":"Next 本命年","type":"integer","decimals":0,"description":"Next lunar year after the current one with the same animal as the birth year."},{"name":"zodiac","label":"Zodiac (生肖)","type":"string","decimals":4,"description":"Animal of the lunar birth year."},{"name":"year_ganzhi_birth","label":"Birth year ganzhi","type":"string","decimals":4,"description":"Sexagenary name of the lunar birth year with pinyin."}],"input_schema":{"type":"object","properties":{"birth_date":{"description":"Gregorian birth date (civil date in China Standard Time), 1900–2100.","type":"string","format":"date","examples":["1990-05-17"]},"reference_date":{"description":"Date on which to evaluate the ages; defaults to the current UTC date.","type":"string","format":"date","default":"today","examples":["2026-09-24"]}},"additionalProperties":false,"required":["birth_date"]},"output_schema":{"type":"object","properties":{"nominal_age_xusui":{"description":"1 at birth plus 1 for every Chinese New Year passed. Unit: sui.","type":"integer","x-unit":"sui"},"actual_age_zhousui":{"description":"Completed years since the Gregorian birthday. Unit: years.","type":"integer","x-unit":"years"},"lunar_birth_date":{"description":"Birth date in the lunar calendar, e.g. 一九九〇年四月廿三.","type":"string"},"lunar_birthday":{"description":"Lunar month and day of birth, e.g. 四月廿三 (4th lunar month, day 23).","type":"string"},"lunar_birthday_this_year":{"description":"Gregorian date of the lunar birthday in the lunar year that contains reference_date (regular-month or day-29 fallback noted when needed).","type":"string","format":"date"},"next_lunar_birthday":{"description":"Gregorian date of the next lunar birthday on or after reference_date.","type":"string","format":"date"},"days_to_next_lunar_birthday":{"description":"0 when reference_date is the lunar birthday. Unit: days.","type":"integer","x-unit":"days"},"current_lunar_year":{"description":"Lunar year containing reference_date with its ganzhi and animal.","type":"string"},"is_benmingnian_now":{"description":"true when the current lunar year has the birth-year animal.","type":"boolean"},"next_benmingnian_year":{"description":"Next lunar year after the current one with the same animal as the birth year.","type":"integer"},"zodiac":{"description":"Animal of the lunar birth year.","type":"string"},"year_ganzhi_birth":{"description":"Sexagenary name of the lunar birth year with pinyin.","type":"string"}}},"formula":"虚岁 = lunar_year(reference_date) − lunar_year(birth_date) + 1; 周岁 = reference year − birth year, minus 1 if the birthday has not yet occurred; lunar birthday in year Y = Gregorian date of (birth lunar month, birth lunar day) in lunar year Y","method":"Ages follow the lunar-year count of the Chinese calendar (New Year at 正月初一, UTC+8); a leap-month birthday is observed in the regular month unless the same leap month recurs, and day 30 falls back to day 29 in 29-day months (a note says when this happens). Traditional calendar/cultural reference calculation; not a prediction, medical, legal or financial advice.","sources":[{"name":"East Asian age reckoning (Wikipedia)","url":"https://en.wikipedia.org/wiki/East_Asian_age_reckoning","type":"reference","retrieved_at":"2026-09-24"},{"name":"Chinese calendar (Wikipedia) – calendar rules as standardised in GB/T 33661-2017","url":"https://en.wikipedia.org/wiki/Chinese_calendar","type":"reference","retrieved_at":"2026-09-24"},{"name":"Hong Kong Observatory – Gregorian-Lunar Calendar Conversion Table","url":"https://www.hko.gov.hk/en/gts/time/conversion.htm","type":"government","retrieved_at":"2026-09-24"}],"freshness":{"type":"daily","max_age_seconds":86400,"note":"Depends on the current date."},"examples":[{"name":"Born 1990-05-17, as of 2026-09-24","inputs":{"birth_date":"1990-05-17","reference_date":"2026-09-24"},"expected":{"nominal_age_xusui":37,"actual_age_zhousui":36,"lunar_birthday":"四月廿三 (4th lunar month, day 23)","lunar_birthday_this_year":"2026-06-08","zodiac":"Horse (马)","year_ganzhi_birth":"庚午 (Gengwu)","next_benmingnian_year":2038},"url":"https://tttkmbb.com/api/v1/calculate/lunar-age?birth_date=1990-05-17&reference_date=2026-09-24"},{"name":"Born 2026-01-01 (before CNY 2026-02-17), as of 2026-03-01","inputs":{"birth_date":"2026-01-01","reference_date":"2026-03-01"},"expected":{"nominal_age_xusui":2,"actual_age_zhousui":0,"zodiac":"Snake (蛇)"},"url":"https://tttkmbb.com/api/v1/calculate/lunar-age?birth_date=2026-01-01&reference_date=2026-03-01"}],"faq":[{"q":"Why is 虚岁 sometimes two years more than my age?","a":"You are 1 sui at birth and gain a year at each Chinese New Year rather than on your birthday, so shortly after New Year and before your birthday 虚岁 = 周岁 + 2."},{"q":"What if I was born in a leap month or on the 30th?","a":"The birthday is observed in the regular month of the same number (the leap month is used only in years where it recurs), and a 30th day becomes the 29th in a 29-day month; the output carries a note whenever a fallback is applied."}],"tags":["xusui","虚岁","chinese age","nominal age","lunar birthday","benmingnian"],"related":[{"calculator_id":"age","reason":"Exact age in years, months and days by the Gregorian calendar."},{"calculator_id":"chinese-zodiac","reason":"Zodiac sign, element and 本命年 list for the birth date."},{"calculator_id":"lunar-calendar-converter","reason":"Full lunar date of the birth or reference date."}],"links":{"html":"https://tttkmbb.com/lunar/lunar-age","markdown":"https://tttkmbb.com/lunar/lunar-age.md","json":"https://tttkmbb.com/lunar/lunar-age.json","api":"https://tttkmbb.com/api/v1/calculate/lunar-age","schema":"https://tttkmbb.com/api/v1/calculators/lunar-age","openapi":"https://tttkmbb.com/openapi.json","mcp":"https://tttkmbb.com/mcp"},"version":"v1","updated_at":"2026-09-24"},"timestamp":"2026-09-24T08:32:19Z"}