POST /bazi/calculate

Core Endpoint

Calculates structured Four Pillars, calendar values, and traditional BaZi mappings from birth date, time, gender, and timezone.

REST API Reference

Accepts YYYY-MM-DD birthDate, HH:mm birthTime, male/female gender, timezone, and language. Returns machine-readable calendar data, Four Pillars, elemental composition, traditional structural mappings, cycle data, and cultural interpretive associations.

Installation

Bash

POST https://api.baziapi.pro/api/v2/bazi/calculate (or /api/v1/bazi/calculate for legacy)

Quick Start

Example Request Body (JSON)

JSON

{
  "birthDate": "1998-08-12",
  "birthTime": "10:30",
  "gender": "male",
  "timezone": "Asia/Shanghai",
  "language": "en"
}

API Parameters

Parameter	Type	Required	Default	Description
`birthDate`	`string`	Required	—	Birth date in YYYY-MM-DD format (e.g. 1998-08-12).
`birthTime`	`string`	Required	—	Birth time in 24-hour HH:mm format (e.g. 10:30). Defaults to 12:00 if omitted.
`gender`	`'male' \| 'female'`	Required	—	Gender for cycle calculation direction.
`timezone`	`string`	Optional	`Asia/Shanghai`	IANA Timezone string (e.g. Asia/Dhaka or Asia/Shanghai).
`language`	`'en' \| 'zh' \| 'hi' \| 'bn' \| 'es'`	Optional	`en`	Output language localization for names, pillars, elements, relationships, and terms: "en" (English), "zh" (Chinese / 中文), "hi" (Hindi / हिन्दी), "bn" (Bengali / বাংলা), "es" (Spanish / Español). Defaults to "en".
`schemaVersion`	`'v2' \| 'v1'`	Optional	`v2`	Schema version toggle: "v2" returns clean canonical grouped schema; "v1" includes legacy top-level aliases.

More Examples

Canonical 200 OK Response Payload (JSON)

JSON

{
  "success": true,
  "statusCode": 200,
  "message": "BaZi calculation completed successfully.",
  "data": {
    "input": {
      "birthDate": "1998-08-12",
      "birthTime": "10:30",
      "gender": "male",
      "timezone": "Asia/Shanghai",
      "language": "en"
    },
    "calendar": {
      "solar": {
        "solarYear": 1998,
        "solarMonth": 8,
        "solarDay": 12,
        "solarHour": 10,
        "solarMinute": 30,
        "solarDateTime": "1998-08-12 10:30:00",
        "weekDay": "Wednesday"
      },
      "lunar": {
        "lunarYear": 1998,
        "lunarMonth": 6,
        "lunarDay": 21,
        "leapMonth": 0,
        "chineseDate": "戊寅年 庚申月 戊午日 丁巳时"
      },
      "solarTerms": {
        "currentSolarTerm": "Li Qiu (Start of Autumn)",
        "previousSolarTerm": "Da Shu (Great Heat)",
        "nextSolarTerm": "Chu Shu (End of Heat)"
      }
    },
    "fourPillars": {
      "yearPillar": "Wu Yin (Earth Tiger)",
      "monthPillar": "Geng Shen (Metal Monkey)",
      "dayPillar": "Wu Wu (Earth Horse)",
      "hourPillar": "Ding Si (Fire Snake)"
    },
    "elementalComposition": {
      "yearElement": "Earth / Wood",
      "monthElement": "Metal / Metal",
      "dayElement": "Earth / Fire",
      "hourElement": "Fire / Fire",
      "statistics": {
        "Wood": "13%",
        "Fire": "38%",
        "Earth": "25%",
        "Metal": "25%",
        "Water": "0%"
      }
    },
    "traditionalMappings": {
      "relationshipMappings": {
        "yearRelationship": "Friend (Bi Jian)",
        "monthRelationship": "Eating God (Shi Shen)",
        "dayRelationship": "Self (Day Master)",
        "hourRelationship": "Direct Resource (Zheng Yin)",
        "distribution": {
          "Friend": "25%",
          "Eating God": "25%",
          "Direct Resource": "25%",
          "Seven Killings": "25%"
        }
      },
      "hiddenStems": {
        "yearHiddenStems": ["Jia (Wood)", "Bing (Fire)", "Wu (Earth)"],
        "monthHiddenStems": ["Geng (Metal)", "Ren (Water)", "Wu (Earth)"],
        "dayHiddenStems": ["Ding (Fire)", "Ji (Earth)"],
        "hourHiddenStems": ["Bing (Fire)", "Geng (Metal)", "Wu (Earth)"]
      },
      "naYin": {
        "yearNaYin": "Earth on City Wall (Cheng Tou Tu)",
        "monthNaYin": "Pomegranate Wood (Shi Liu Mu)",
        "dayNaYin": "Heavenly Fire (Tian Shang Huo)",
        "hourNaYin": "Sand Middle Earth (Sha Zhong Tu)"
      }
    },
    "zodiac": {
      "chineseZodiac": "Tiger (Yin)",
      "animal": "Tiger"
    },
    "cycleData": {
      "majorCyclePeriods": {
        "direction": "Forward",
        "forward": true,
        "startingAge": 7,
        "startingDate": "2005-06-18",
        "pillars": [
          { "age": 7, "pillar": "Xin You (Metal Rooster)" },
          { "age": 17, "pillar": "Ren Xu (Water Dog)" }
        ]
      }
    },
    "traditionalInterpretations": {
      "dayMasterStrength": "Strong",
      "strongestElement": "Fire",
      "weakestElement": "Water",
      "supportingElementAssociations": ["Metal", "Water", "Wood"],
      "challengingElementAssociations": ["Fire", "Earth"],
      "usefulElementReference": "Metal",
      "traditionalCareerAssociation": "West or North or East",
      "traditionalWealthAssociation": "High",
      "traditionalHealthAssociations": ["Kidneys/Urinary", "Lungs/Respiratory"]
    },
    "currentAnnualCycle": {
      "currentYear": 2026,
      "annualPillar": "Bing Wu",
      "traditionalAssessment": "Good",
      "traditionalThemes": ["Career Advancements", "Personal Growth"]
    },
    "disclaimer": {
      "type": "traditional-interpretation",
      "text": "BaZi interpretations are derived from traditional Chinese cultural and calendrical practices and are provided for cultural and informational purposes only. These interpretations are not scientifically validated predictions and do not guarantee future events or outcomes. They should not be relied upon as medical, financial, legal, career, or other professional advice."
    }
  }
}

Hindi Localized Response (हिन्दी - hi)

JSON

{
  "success": true,
  "statusCode": 200,
  "message": "BaZi calculation completed successfully.",
  "data": {
    "input": {
      "birthDate": "1998-08-12",
      "birthTime": "10:30",
      "gender": "male",
      "timezone": "Asia/Kolkata",
      "language": "hi"
    },
    "calendar": {
      "solar": {
        "solarDateTime": "1998-08-12 10:30:00",
        "weekDay": "बुधवार"
      },
      "solarTerms": {
        "currentSolarTerm": "शरद ऋतु आरंभ (Li Qiu)"
      }
    },
    "fourPillars": {
      "yearPillar": "वू-यिन (यांग पृथ्वी बाघ)",
      "monthPillar": "गेन्ग-शेन (यांग धातु वानर)",
      "dayPillar": "शिन-माओ (यिन धातु खरगोश)",
      "hourPillar": "गुई-सी (यिन जल सर्प)",
      "advancedPillars": {
        "taiYuan": "शिन-हाई (यिन धातु सूअर)",
        "mingGong": "बिंग-चेन (यांग अग्नि ड्रैगन)",
        "shenGong": "जिया-यिन (यांग काष्ठ बाघ)"
      }
    },
    "elementalComposition": {
      "yearElement": "पृथ्वी / काष्ठ",
      "monthElement": "धातु / धातु",
      "dayElement": "धातु / काष्ठ",
      "hourElement": "जल / अग्नि"
    },
    "traditionalMappings": {
      "relationshipMappings": {
        "yearRelationship": "प्रत्यक्ष संसाधन",
        "monthRelationship": "धन हरण",
        "dayRelationship": "दिन का स्वामी",
        "hourRelationship": "आहार देव",
        "distribution": {
          "प्रत्यक्ष संसाधन": "31%",
          "धन हरण": "23%",
          "आहार देव": "8%",
          "प्रत्यक्ष धन": "8%",
          "प्रत्यक्ष अधिकारी": "15%"
        }
      },
      "hiddenStems": {
        "yearHiddenStems": ["जिया (काष्ठ)", "बिंग (अग्नि)", "वू (पृथ्वी)"]
      },
      "naYin": {
        "yearNaYin": "प्राचीर पृथ्वी"
      }
    },
    "traditionalInterpretations": {
      "dayMasterStrength": "सशक्त",
      "strongestElement": "धातु",
      "weakestElement": "जल"
    },
    "zodiac": {
      "chineseZodiac": "बाघ",
      "animal": "बाघ"
    }
  }
}

cURL Example Command

Bash

curl -X POST https://api.baziapi.pro/api/v2/bazi/calculate \
  -H "x-api-key: bazi_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "birthDate": "1998-08-12",
    "birthTime": "10:30",
    "gender": "male",
    "timezone": "Asia/Shanghai",
    "language": "hi"
  }'

Rate Limits & Quotas

Multi-Language & Localization

Something unclear? Contact developer support.