USAGE_EXAMPLES.md

📖 Ziwei Doushu API - Usage Examples

🚀 Quick Start

1. Calculate Ziwei Chart

Request:

curl -X POST https://sisithefox-astrology-ziwei-api.hf.space/calculate-ziwei \
  -H "Content-Type: application/json" \
  -d '{
    "birth_date": "2000-1-1",
    "birth_time": "14:30",
    "gender": "男",
    "is_leap_month": false,
    "fix_leap": true
  }'

Response:

{
  "status": "success",
  "data": {
    "solar_date": "2000-1-1 14:30",
    "lunar_date": "一九九九年冬月廿五",
    "chart": {
      "solar": "2000-1-1",
      "lunar": "一九九九年冬月廿五",
      "gender": "男",
      "sign": "摩羯座",
      "zodiac": "兔",
      "earthly_branch_index": 7
    },
    "palaces": [
      {
        "name": "命宫",
        "position": 3,
        "heavenly_stem": "己",
        "earthly_branch": "巳",
        "major_stars": ["太阴"],
        "minor_stars": ["天马", "铃星", "陀罗"]
      },
      ...
    ]
  }
}

---

🔗 Integration Examples

JavaScript / TypeScript

interface ZiweiRequest {
  birth_date: string;    // "YYYY-M-D" format
  birth_time: string;    // "HH:MM" format
  gender: '男' | '女';
  is_leap_month?: boolean;
  fix_leap?: boolean;
}

async function calculateZiwei(data: ZiweiRequest) {
  const response = await fetch(
    'https://sisithefox-astrology-ziwei-api.hf.space/calculate-ziwei',
    {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(data)
    }
  );

  return response.json();
}

// Usage
const result = await calculateZiwei({
  birth_date: '2000-1-1',
  birth_time: '14:30',
  gender: '男',
  fix_leap: true
});

console.log(result.data.chart.sign);  // "摩羯座"
console.log(result.data.palaces[3]);  // 命宫数据

Python

import requests

def calculate_ziwei(birth_date, birth_time, gender='男'):
    url = 'https://sisithefox-astrology-ziwei-api.hf.space/calculate-ziwei'
    data = {
        'birth_date': birth_date,
        'birth_time': birth_time,
        'gender': gender,
        'is_leap_month': False,
        'fix_leap': True
    }

    response = requests.post(url, json=data)
    return response.json()

# Usage
result = calculate_ziwei('2000-1-1', '14:30', '男')
print(result['data']['chart']['sign'])       # 摩羯座
print(result['data']['chart']['zodiac'])     # 兔

---

📊 Response Data Structure

Chart (基础信息)

• solar - 公历日期
• lunar - 农历日期
• gender - 性别
• sign - 星座 (西方星座)
• zodiac - 生肖

Palaces (十二宫位)

每个宫位包含：

• name - 宫位名称 (命宫、财帛、事业等)
• position - 宫位索引 (0-11)
• heavenly_stem - 天干
• earthly_branch - 地支
• major_stars - 主星 (紫微、天机、太阳等)
• minor_stars - 辅星 (文昌、文曲、左辅等)

Star Types (星曜类型)

• 主星 (Major Stars): 紫微、天机、太阳、武曲、天同、廉贞、天府、太阴、贪狼、巨门、天相、天梁、七杀、破军
• 辅星 (Minor Stars): 文昌、文曲、左辅、右弼、天魁、天钺、禄存、擎羊、陀罗、火星、铃星、地空、地劫、天马

---

⏰ Time Format Notes

Birth Time Format: Use 24-hour format HH:MM

The API automatically converts to traditional Chinese 12 time periods (十二时辰):

• 子时 (23:00-01:00)
• 丑时 (01:00-03:00)
• 寅时 (03:00-05:00)
• 卯时 (05:00-07:00)
• 辰时 (07:00-09:00)
• 巳时 (09:00-11:00)
• 午时 (11:00-13:00)
• 未时 (13:00-15:00)
• 申时 (15:00-17:00)
• 酉时 (17:00-19:00)
• 戌时 (19:00-21:00)
• 亥时 (21:00-23:00)

---

🌙 Leap Month Handling

If the birth date is in a lunar leap month (闰月):

{
  "birth_date": "2023-2-20",
  "birth_time": "12:00",
  "gender": "女",
  "is_leap_month": true,   // ← Set this to true
  "fix_leap": true
}

---

🔍 Error Handling

try {
  const result = await calculateZiwei({...});

  if (result.status === 'success') {
    // Process data
    console.log(result.data);
  }
} catch (error) {
  if (error.response?.status === 500) {
    console.error('Calculation error:', error.response.data.detail);
  } else if (error.response?.status === 422) {
    console.error('Invalid input:', error.response.data);
  }
}

---

💡 Tips

1. Date Format: Use YYYY-M-D (single digit OK) instead of YYYY-MM-DD
2. Gender: Use Chinese characters '男' or '女'
3. Performance: Average response time < 500ms
4. Rate Limit: Reasonable use, no hard limit

---

🔗 Related APIs

• BaZi API: astrologybazi-api
• Website: astrologybazi.com

---

🦊 Powered by iztro - MIT License

💕 Generated with Sisi & TH Studio ✨