Tử Vi Đẩu Số API

Standalone PHP REST API for Purple Star Astrology (紫微斗數 / Tử Vi Đẩu Số).
No framework, no database required — pure PHP calculation engine.

Endpoints

GET /api/calculate

Calculate a Zi Wei Dou Shu birth chart.

Parameters

Param	Required	Example	Description
date	✅	1990-06-15	Solar birth date (YYYY-MM-DD)
time	✅	08:30	Birth time (HH:MM, 24h)
gender	✅	nam / nu	Gender (nam = male, nu = female)
year	❌	2025	Year to read fortune (default: current year)
school	❌	trung_chau	School of interpretation: trung_chau (Tam Hợp), thu_man (Phi Tinh), bac_phai

Example

GET /api/calculate?date=1990-06-15&time=08:30&gender=nam&year=2025

Response

{
  "ok": true,
  "input": { "date": "1990-06-15", "time": "08:30", "gender": "nam" },
  "solar_time": { "true_solar_time": "08:22", "eot_minutes": -2.4, ... },
  "lunar": { "day": 23, "month": 5, "year": 1990, "year_can_chi": "Canh Ngọ" },
  "hour_chi": "Thìn",
  "cuc": { "num": 5, "name": "Thổ Ngũ Cục" },
  "yin_yang": "Dương",
  "direction": "Thuận",
  "menh_cung": { "chi": "Dần", "can": "Mậu" },
  "si_hua": {
    "Hóa Lộc": "Thái Âm",
    "Hóa Quyền": "Tham Lang",
    "Hóa Khoa": "Thiên Lương",
    "Hóa Kỵ": "Thiên Đồng"
  },
  "cach_cuc": [ { "name": "Sát Phá Lang", "matched": 3, "total": 3 } ],
  "palaces": [
    {
      "index": 0, "chi": "Dần", "name": "Mệnh", "is_menh": true,
      "stars": ["Thất Sát", "Tả Phụ", "Thiên Đức"],
      "star_meta": { "Thất Sát": { "brightness": "Vượng" } },
      "dai_han": { "age_start": 3, "age_end": 12, "can_chi": "Đinh Mão" }
    }
    ...
  ]
}

GET /api/health

Returns service status.

---

Installation

1. Clone or download this repo to your web server (Apache/Nginx with PHP 8.0+)
2. Point your domain to the repo root
3. Make sure mod_rewrite is enabled (Apache) or configure Nginx rewrites

Nginx example:

location /api/ {
    try_files $uri $uri/ /api/index.php?$query_string;
}

---

Features

• ✅ True Solar Time correction (Equation of Time + longitude)
• ✅ 14 chính tinh placement (Purple Star, Sky Horse, etc.)
• ✅ 55+ phụ tinh (auxiliary stars including Thiên Thương, Thiên Sứ)
• ✅ 3 star cycles: Tràng Sinh (12), Bác Sĩ (year stem), Thái Tuế (year branch)
• ✅ Tứ Hóa (Four Transformations) — 3 schools: Trung Châu, Thư Mân, Bắc Phái
• ✅ Tuần + Triệt (Empty branches)
• ✅ Đại vận + Tiểu vận (Major & Minor periods) + Hạn năm (Annual luck)
• ✅ 21 Cách cục (Special formations) detection
• ✅ Lưu tinh (Annual transiting stars)
• ✅ Zero WordPress/framework dependencies

---

License

MIT — free to use, modify, and redistribute.

---

Maintained by truyennghe.com