API Documentation

API Shop Metaphysics Algorithm API Guide

Quick Start

After registering, create an API key in the console to call algorithm endpoints via HTTP. All endpoints return JSON.

# Get BaZi chart (GET request)
curl "https://www.zfate.com/api/bazi?date_type=1&year=1990&month=6&day=15&hour=10&sex=1&name=张三&lang=zh-CN" \
  -H "X-API-Key: your_key_here"

Authentication

All API requests must include the API key in the HTTP Header:

X-API-Key: <your_api_key>

Or pass via query parameter: ?api_key=your_key

Create and manage keys in Console → Keys

Common Parameters

The following parameters are shared by both /api/bazi and /api/bazi/fortune

Parameter Type Required Default Description
date_type int No 1 Date type: 1=Solar, 2=Lunar
year int No Current year Birth year (1~9999)
month int No Current month Birth month (1~12)
day int No Current day Birth day (1~31)
hour int No Current hour Birth hour (0~23, 24h format)
sex int No 1 Gender: 1=Male, 0=Female
name string No Empty Name (display only)
lang string No zh-CN Response language: zh-CN=Simplified, zh-TW=Traditional, en=English

Invalid parameter values will automatically fall back to the current time, but date validity (e.g. Feb 30) will be validated and return a 400 error.

Response Format

{
  "code": 200,
  "message": "success",
  "data": { ... }
}
Field Type Description
code int Status code, 200 means success
message string Status description
data object/null Business data, may be null on failure

API Details

GET /api/bazi

Get complete BaZi chart based on birth time, including four pillars, five elements, ten gods, spiritual stars, luck cycles, destiny, useful gods, analysis, and current fortune.

This endpoint automatically locates the current decade/year/month/day fortune without extra parameters.

Request Parameters

See Common Parameters, no extra parameters.

Response Fields

Field Name Type Description
lang string Response language
solar string Solar birth time (YYYY-MM-DD HH:00)
lunar string Lunar birth time
name string Name
gender int Gender: 1=Male, 0=Female
age int Age (full years)
zodiac string Zodiac
constellation string Constellation
solarTerm string Solar term
yinYang string Year stem yin/yang (yang/yin)
riZhu string Day pillar stem
fiveElements object Five elements stats + strength
fourPillars object Four pillars info (stem-branch, stems, branches, nayin, ten gods, star stages, self-sitting, void, hidden stems, combinations)
usefulGods object Useful gods (useful/joyful/taboo/enemy/idle)
spiritStars object Spiritual stars (per pillar)
decadeFortune array Decade fortune list (all steps)
yearFortune array Year fortune list
destiny object Destiny chart info (life palace, body palace, tai yuan, tai xi, luck onset, destiny type, strength)
currentFortune object Current fortune (auto-located to current decade/year/month/day)
analysis object BaZi analysis text (personality, career, wealth, marriage, health, etc.)
decadeFortuneAnalysis object Decade fortune + year fortune analysis (pre-onset + 9 decades x 10 years)
chuanGongPalace array Chuan Gong pressure (blind school)
ganZhiAnalysis array Stem-branch clash/combine/harm analysis (natal + current decade/year triggers)

Request Example

# Solar: 1990-06-15 10:00 Male
curl "https://www.zfate.com/api/bazi?date_type=1&year=1990&month=6&day=15&hour=10&sex=1&name=张三&lang=zh-CN" \
  -H "X-API-Key: your_key_here"

Response Example (simplified)

{
  "code": 200,
  "message": "success",
  "data": {
    "lang": "zh-CN",
    "solar": "1990-06-15 10:00",
    "lunar": "庚午年五月廿三日 巳时",
    "name": "张三",
    "gender": 1,
    "age": 35,
    "zodiac": "马",
    "constellation": "双子座",
    "solarTerm": "芒种",
    "riZhu": "辛",
    "fiveElements": { ... },
    "fourPillars": { ... },
    "usefulGods": { ... },
    "spiritStars": { ... },
    "decadeFortune": [ ... ],
    "destiny": { ... },
    "currentFortune": { ... },
    "analysis": { ... },
    "decadeFortuneAnalysis": { ... },
    "chuanGongPalace": [ ... ],
    "ganZhiAnalysis": [ ... ]
  }
}

currentFortune Location Rules

This endpoint automatically locates today's fortune on each request:

  1. 1. Uses current time to determine the current solar year/month/day
  2. 2. Iterates the decade fortune list to find the one containing the current year
  3. 3. Fills yearFortune with all 10 years of that decade
  4. 4. Monthly pillars are calculated for 12 months of the current year
  5. 5. Daily pillars are calculated for each day of the current month
  6. 6. ganZhiAnalysis recalculates triggers using natal + current decade + current year

Error Codes

HTTP Status code Description
200 200 Request successful
400 400 Bad request (invalid date, hierarchy violation, etc.)
401 401 API key not provided
403 403 API key invalid or disabled
429 429 Daily call limit exceeded

If you encounter issues, contact support or check Usage