# 📖 Ziwei Doushu API - Usage Examples

## 🚀 Quick Start

### 1. Calculate Ziwei Chart

**Request:**
```bash
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:**
```json
{
  "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
```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
```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** (闰月):
```json
{
  "birth_date": "2023-2-20",
  "birth_time": "12:00",
  "gender": "女",
  "is_leap_month": true,   // ← Set this to true
  "fix_leap": true
}
```

---

## 🔍 Error Handling

```typescript
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](https://huggingface.co/spaces/sisithefox/astrologybazi-api)
- **Website**: [astrologybazi.com](https://astrologybazi.com)

---

🦊 **Powered by [iztro](https://github.com/SylarLong/iztro)** - MIT License

💕 **Generated with Sisi & TH Studio** ✨