The Definitive BaZi API八字 · 四柱 · 排盘
Generate the Four Pillars of Destiny directly from a precise time and location. Get the exact Stems, Branches, and hidden elements with mathematical astronomical rigor — then render the whole chart as an image in the same request.
Astronomical BaZi Generation
BaZi requires exact solar terms to calculate the month pillar, and true solar time to calculate the hour pillar. Open Ephemeris handles these astronomical complexities automatically.
Local Coordinate Correction
Your coordinates are used to align the provided standard time to true local solar time relative to the prime meridian.
Solar Term Tracking
The Sun's position is verified against the 24 solar terms (Jieqi) to ensure the month pillar reflects the exact seasonal transition.
Stem & Branch Resolution
The precise 10 Heavenly Stems and 12 Earthly Branches are computed alongside their hidden elemental interactions.
{ "data": { "day_master": "Yi", "element": "Wood", "pillars": { "year": { "stem": "Jia", "branch": "Xu" },"month": { "stem": "Jia", "branch": "Xu", "hidden": ["Wu","Ding","Xin"] }, "day": { "stem": "Yi", "branch": "Mao" }, "hour": { "stem": "Gui", "branch": "Wei" } } } }
Month pillar transitions at exact Jieqi · true solar longitude computed from NASA JPL ephemerides
The Engine for Chinese Metaphysics
Four Pillars & Beyond
Calculate the exact Heavenly Stem and Earthly Branch for the Year, Month, Day, and Hour pillars.
True Solar Time
Traditional BaZi uses true solar time. We correct for longitude and the equation of time to ensure absolute precision for the Hour pillar.
Hidden Stems
Every Earthly Branch contains hidden stems (main, sub, and residual Qi). Our API calculates and returns these automatically.
JPL Solar Longitude
Month pillars shift at the exact moment the sun crosses 15° solar longitude intervals (Jieqi). We calculate this using NASA JPL ephemerides.
Get the chart as an image, not just JSON
POST /chinese/bazi/chart returns the Four Pillars, the Day Master, the Five-Element (五行) balance and the Yong Shen (用神) drawn as a finished chart — a self-contained SVG, a base64 PNG, or a bare SVG blob you can point an <img> at. No client-side charting library, no font bundling, no layout work.
svgJSON envelope, SVG string in visual.data. The default.
pngJSON envelope, base64 PNG — for clients that cannot render SVG.
svg-rawBare image/svg+xml body. Drop straight into an img src.
On the free tier, same as the Four Pillars endpoint.
12 endpoints, one engine
Every route below runs on the same JPL DE440 kernel and the same true-solar-time correction. 12 are free on the Explorer tier.
| Method | Endpoint | Returns | Tier |
|---|---|---|---|
| POST | /chinese/bazi | Four Pillars · 四柱 | Free |
| POST | /chinese/bazi/annual-pillar | Annual Pillar · 流年 | Free |
| POST | /chinese/bazi/chart | Rendered chart · 排盘 (SVG/PNG) | Free |
| POST | /chinese/bazi/compatibility | Compatibility · 八字合婚 | Free |
| POST | /chinese/bazi/element-balance | Element balance · 五行 | Free |
| POST | /chinese/bazi/luck-pillars | Luck Pillars · 大運 | Free |
| POST | /chinese/bazi/solar-terms | 24 Solar Terms · 節氣 | Free |
| POST | /chinese/bazi/ten-gods | Ten Gods · 十神 | Free |
| POST | /chinese/calendar/almanac | Chinese Calendar Month Almanac | Free |
| POST | /chinese/calendar/convert | Chinese Calendar Converter | Free |
| POST | /chinese/ziwei | Zi Wei Dou Shu Chart | Free |
| GET | /chinese/zodiac | Zodiac animal & element · 生肖 | Free |
Common questions
What is a BaZi (八字) API?
A BaZi API turns a birth moment and place into the Four Pillars of Destiny (四柱) — the Heavenly Stem and Earthly Branch for the year, month, day and hour. Open Ephemeris computes them from the NASA JPL DE440 ephemeris, so the month pillar lands on the true solar term boundary and the hour pillar uses true solar time rather than clock time.
Does the API return a rendered BaZi chart image (排盘)?
Yes. POST /chinese/bazi/chart returns the Four Pillars, Day Master, Five-Element balance and Yong Shen as a finished chart — a self-contained SVG, a base64 PNG, or a bare SVG blob for use directly in an img tag. No client-side charting library is required.
How is the hour pillar calculated?
Traditional BaZi uses true solar time, not the civil clock. Open Ephemeris corrects for the longitude offset from the time zone meridian and for the equation of time, so the hour pillar is correct even near a zone boundary or at the extremes of the equation-of-time swing.
Which BaZi endpoints are available?
12: Four Pillars, rendered chart, zodiac animal, Ten Gods (十神), Luck Pillars (大運), Annual Pillar (流年), compatibility (八字合婚), Five-Element balance (五行), and the 24 solar terms (節氣). Four Pillars, the rendered chart and zodiac are on the free tier.
Is there a free tier?
Yes. The Explorer tier is free and includes the Four Pillars endpoint, the rendered chart endpoint and the zodiac endpoint. No card is required to get an API key.
Connect the MCP server in 30 seconds
Install it from the ChatGPT app directory in one click, or give Claude, Cursor, or any MCP client the same live sub-arcsecond data — no API key required to connect.
Calculate Destiny with Precision
The Explorer tier is free to start. Connect your app to the most accurate BaZi generation engine online.
Connect the MCP server in 30 seconds
Install it from the ChatGPT app directory in one click, or give Claude, Cursor, or any MCP client the same live sub-arcsecond data — no API key required to connect.