BaZi Four Pillars API
Build a Chinese Four Pillars view with inspectable time conventions. The response keeps stems, branches, hidden stems and symbolic relationships as structured facts rather than hiding them in a prose-only reading.
POST /v1/chinese/bazi50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗
What this API provides.
Get Four Pillars, hidden stems, ten gods, visible element counts and pillar relations with explicit civil-time and Beijing solar-term conventions.
Stem/branch elements, polarity, animal and hidden stems
Ten-god labels relative to the day master
Visible element counts and selected stem/branch relations
Send
- birth.date and IANA timezone
- Local time when known; an unknown time omits the hour pillar
- Locale; no longitude-based true-solar correction is applied
Receive
- pillars with stems, branches and hidden-stem detail
- five_elements.counts and selected pillar relations
- A declared day-boundary/solar-term method and fact-linked prose
Four pillars, visible facts.
This view is drawn directly from the sample JSON. It is not a weighted strength assessment.
metal / fire · horse
metal / fire · snake
fire / earth · dog
wood / earth · goat
Real input. Real output.
Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.
{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
}
}{
"request_id": "8391c2e0597c12c18e10a847981e38a2",
"api_version": "v1",
"locale": "en",
"data": {
"pillars": {
"year": {
"gan_zhi": "庚午",
"stem": "庚",
"branch": "午",
"stem_element": "metal"
},
"month": {
"gan_zhi": "辛巳",
"stem": "辛",
"branch": "巳",
"stem_element": "metal"
},
"day": {
"gan_zhi": "丙戌",
"stem": "丙",
"branch": "戌",
"stem_element": "fire"
},
"hour": {
"gan_zhi": "乙未",
"stem": "乙",
"branch": "未",
"stem_element": "wood"
}
},
"day_master": {
"stem": "丙",
"element": "fire"
},
"five_elements": {
"counts": {
"wood": 1,
"fire": 3,
"earth": 2,
"metal": 2
},
"basis": "visible stems and branch primary elements; unweighted, excludes hidden stems",
"complete": true
},
"relations": [
{
"type": "six_combination",
"pillars": [
"year"
],
"branches": [
"午"
]
},
{
"type": "stem_combination",
"pillars": [
"year"
],
"stems": [
"庚"
]
}
],
"method": {
"library": "lunar-python",
"library_version": "1.4.8",
"sect": 2,
"day_boundary": "local civil midnight",
"year_boundary": "Li Chun exact instant",
"month_boundary": "Jie exact instant",
"term_reference_timezone": "UTC+08:00 converted to birth instant"
}
},
"interpretation": {
"locale": "en",
"kind": "chinese/bazi",
"disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
"coverage": {
"total_facts": 8,
"selected_facts": 8,
"omitted_count": 0,
"selection_method": "all-source-facts-v1",
"full_numeric_data_unchanged": true
},
"method": {
"engine": "celestack-original-rules-v1",
"corpus": "celestack-original-compositional-v1",
"corpus_version": "2026-11-17.2",
"fallback_locale": null,
"editorial_status": "agent-authored; independent linguistic review pending",
"predictive_validity": "symbolic interpretations are not scientifically validated predictions",
"chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
},
"items": [
{
"fact_id": "chinese.pillar.year",
"title": "Year pillar",
"text": "Year pillar: 庚午. Stem element: Metal; branch element: Fire; polarity: Yang. Symbolic reflection: structure and boundaries. These calendar symbols do not establish personal traits or future events.",
"source": {
"id": "chinese.pillar.year",
"type": "chinese_pillar",
"position": "year",
"gan_zhi": "庚午",
"stem": "庚",
"branch": "午",
"stem_element": "metal",
"branch_element": "fire",
"polarity": "yang",
"animal": "horse",
"ten_god": "indirect_wealth",
"hidden_stems": [
{
"stem": "丁",
"element": "fire",
"ten_god": "rob_wealth"
},
{
"stem": "己",
"element": "earth",
"ten_god": "hurting_officer"
}
]
}
}
]
},
"warnings": [],
"credits_used": 5
}The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.
cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/chinese/bazi' \
+ --header 'Authorization: Bearer YOUR_API_KEY' \
+ --header 'Content-Type: application/json' \
+ --header 'Idempotency-Key: bazi-api-example-001' \
+ --data '{
"locale": "en",
"birth": {
"date": "1990-05-21",
"time": "14:30:00",
"timezone": "Europe/Madrid",
"latitude": 40.4168,
"longitude": -3.7038
}
}'Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗
Ways to use it.
- Four Pillars onboarding and chart displays
- A visible-element visualization with explicit counting rules
- Localized symbolic readings backed by pillar facts
12 response locales
English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.
Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.
Limits and interpretation.
- Year/month pillars use the real instant against Beijing solar-term boundaries; day/hour pillars use local civil time.
- There is no longitude or true-solar-time correction. Visible element counts are not a full weighted strength or useful-god analysis.
- Luck pillars, annual fortune predictions and remedies are not included. Unknown-time boundary uncertainty is explicit.
Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗
Choose your billing.
Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.
Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.
Frequently asked questions.
Does the endpoint use true solar time?
No. The declared profile uses local civil time for day/hour pillars, with year/month solar-term boundaries evaluated at the real instant in Beijing time.
Are element counts a strength assessment?
No. They count the visible stem and branch elements. They are not a weighted hidden-stem, seasonal-strength or useful-god assessment.
Can I omit the birth time?
Yes. The hour pillar is omitted. If a solar-term boundary makes the year or month pillar uncertain within that local day, the relevant pillar is also marked uncertain.
What does access cost?
Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 5 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.