Integrating a new API begins with understanding its data contract. The BaZi API enforces strict typing and deterministic schemas to ensure enterprise predictability. This guide walks through every request field and dissects the comprehensive response object returned by the POST /api/v1/bazi/calculate endpoint.
Request Parameters: What You Send
The calculation endpoint requires minimal inputs to produce an exhaustive chart: birthDate (ISO format YYYY-MM-DD), birthTime (24-hour HH:mm), gender ('male' | 'female', used for Luck Pillar direction calculation), and timezone (standard IANA timezone string).
{
"birthDate": "1990-10-24",
"birthTime": "08:30",
"gender": "female",
"timezone": "America/New_York",
"language": "en"
}The Pillars Object: Four Temporal Anchors
The core of the response is the 'pillars' dictionary, containing 'year', 'month', 'day', and 'hour'. Each entry provides the Heavenly Stem and Earthly Branch in both English romanization and authentic Chinese characters, alongside the associated Ten God and hidden stems.
"pillars": {
"year": {
"stem": "Geng",
"branch": "Wu",
"stemChinese": "庚",
"branchChinese": "午",
"tenGod": "Direct Officer",
"element": "Metal",
"naYin": "Roadside Earth"
},
"day": {
"stem": "Ding",
"branch": "Chou",
"stemChinese": "丁",
"branchChinese": "丑",
"isDayMaster": true
}
}Day Master (日主) and Five Elements Distribution
The Day Master represents the subject's baseline elemental character. The API computes the Day Master's element (Wood, Fire, Earth, Metal, Water) and polarity (Yin or Yang). Furthermore, an aggregate 'fiveElements' summary provides absolute counts and percentage weightings across the entire chart, allowing instant elemental balance analysis.
Luck Pillars (大运): Sequential Decadal Cycles
In traditional Chinese chronobiology, cycles progress through 10-year Luck Pillars (Da Yun). The starting age and progression direction (forward or backward) depend on the interaction between birth gender and the Yin/Yang polarity of the Year Pillar stem. The API returns the exact starting age (e.g. age 6.4), transition year, and the full sequence of upcoming decadal pillars.
Conclusion & Key Takeaways
With standard JSON structures and comprehensive calendrical parameters, the BaZi API empowers engineers to ingest rich chronological data directly into PostgreSQL tables, mobile state stores, or AI agent context windows.