Back to Docs
BaZi (Four Pillars of Destiny)

BaZi (Four Pillars of Destiny)

POST/api/v1/chinese/bazi

Calculate the complete Four Pillars of Destiny (八字) chart based on birth date, time, and location. Includes Day Master analysis, Ten Gods, Life Stages, element balance, and optional professional features.

Full URL

https://api.freeastroapi.com/api/v1/chinese/bazi

Available Features

Four Pillars

Year, Month, Day, Hour with Stems & Branches

Always
Ten Gods

Relationship of each stem to Day Master

include_ten_gods
Hidden Stems

Inner energies within each branch

Always
Life Stages

12 Di Shi (growth stages) per pillar

Always
Luck Cycle

10-year Da Yun periods from birth

Always
Element Balance

Five elements point distribution

Always
Pinyin

Romanization for Chinese characters

include_pinyin
Stars (Shen Sha)

Tian Yi, Peach Blossom, etc.

include_stars
Interactions

Combinations, Clashes, Harms, Punishments

include_interactions
Professional

DM Strength, Structure, Yong Shen analysis

include_professional
Debug

Time corrections and professional calculation details

include_debug
Current Flow

Current annual-flow triggers

include_current_flow

Time Standard Options

civil (default)

Uses standard clock time directly. Best for modern births.

true_solar

Applies longitude and equation-of-time corrections relative to the timezone's standard meridian.

true_solar_absolute

Uses local mean time plus the equation of time, independent of the civil timezone offset.

Request Parameters

Field
year
Type
integer
Required
Yes
Description
Year of birth (1 or greater).
Field
month
Type
integer
Required
Yes
Description
Month of birth (1-12)
Field
day
Type
integer
Required
Yes
Description
Day of birth (1-31)
Field
hour
Type
integer
Required
No
Description
Hour of birth (0-23). Default: 12.
Field
minute
Type
integer
Required
No
Description
Minute of birth (0-59). Default: 0.
Field
city
Type
string
Required
No
Description
City used for coordinate lookup. Supply either a resolvable city or both lat and lng.
Field
lat
Type
number
Required
No
Description
Latitude (-90 to 90). Required with lng when city is omitted.
Field
lng
Type
number
Required
No
Description
Longitude (-180 to 180). Required with lat when city is omitted.
Field
sex
Type
"M" | "F"
Required
No
Description
Affects luck-cycle direction. Case-insensitive. Default: M.
Field
time_standard
Type
string
Required
No
Description
civil, true_solar, or true_solar_absolute. Default: civil.
Field
calendar
Type
string
Required
No
Description
gregorian or julian. Julian dates are converted to the equivalent Gregorian instant before calculation. Default: gregorian.
Field
tz_str
Type
string
Required
No
Description
IANA timezone name or AUTO. AUTO may resolve historical dates to Local Mean Time. Default: AUTO.
Field
include_ten_gods
Type
boolean
Required
No
Description
Include Ten Gods in each public pillar. Default: true.
Field
include_pinyin
Type
boolean
Required
No
Description
Include Pinyin throughout the response. Default: true.
Field
include_stars
Type
boolean
Required
No
Description
Include Shen Sha (symbolic stars). Default: true.
Field
include_interactions
Type
boolean
Required
No
Description
Include combinations, clashes, harms, breaks, and punishments. Default: true.
Field
include_professional
Type
boolean
Required
No
Description
Include Day Master strength, structure, Yong Shen, and favorable/unfavorable elements. Default: true.
Field
include_debug
Type
boolean
Required
No
Description
Include calculation and professional debug data. Default: true.
Field
include_current_flow
Type
boolean
Required
No
Description
Include current annual-flow triggers. Default: false.
In engine version 1.4.0 and later, favorable_elements and unfavorable_elements are mutually exclusive.

Sample Code

curl -X POST "https://api.freeastroapi.com/api/v1/chinese/bazi" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "lat": 28.6139,
    "lng": 77.2090,
    "city": "New Delhi",
    "sex": "M",
    "time_standard": "civil",
    "calendar": "gregorian",
    "tz_str": "Asia/Kolkata",
    "include_ten_gods": true,
    "include_pinyin": true,
    "include_stars": true,
    "include_interactions": true,
    "include_professional": true,
    "include_debug": false
}'

Response Data

{
  "day_master": {
    "stem": "庚",
    "pinyin": "gēng",
    "info": {
      "name": "Geng",
      "element": "Metal",
      "polarity": "Yang"
    }
  },
  "pillars": [
    {
      "label": "year",
      "gan": "庚",
      "zhi": "午",
      "gan_pinyin": "gēng",
      "zhi_pinyin": "wǔ",
      "ten_gods": {
        "stem": "Friend",
        "hidden": [
          { "gan": "丁", "ten_god": "Direct Officer" },
          { "gan": "己", "ten_god": "Direct Resource" }
        ]
      },
      "nayin": "路旁土",
      "life_stage": { "chinese": "沐浴", "name": "Bath" }
    }
  ],
  "elements": {
    "points": {
      "Wood": 5,
      "Fire": 75,
      "Earth": 40,
      "Metal": 90,
      "Water": 5
    },
    "dominant": "Metal"
  },
  "professional": {
    "dm_strength": "Weak",
    "structure": "7 Killings Structure",
    "yong_shen_candidates": ["Metal (Jin)", "Earth (Tu)"],
    "favorable_elements": ["Metal (Jin)", "Earth (Tu)"],
    "unfavorable_elements": ["Water (Shui)", "Fire (Huo)"]
  },
  "metadata": {
    "engine_version": "1.4.0",
    "ruleset": "Standard Traditional (SwissEph)"
  }
}

Related Endpoints

BaZi Flow

Annual and monthly forecasting

Dictionary

Interaction and star ID mappings

Showcase Example

See what you can build with our BaZi API. our official open-source calculator demonstrates how to visualize the four pillars, luck cycles, and element balance using this exact endpoint.

View BaZi Calculator on GitHub