Spaces:
Running
Running
|
Download README.md from sisithefox/astrologybazi-api: direct link, hf CLI and curl.
- Browser
- Download file 15.9 kB
-
https://huggingface.co/spaces/sisithefox/astrologybazi-api/resolve/main/README.md
- Command line
-
hf download hf://spaces/sisithefox/astrologybazi-api/README.md
-
curl -L -o README.md https://huggingface.co/spaces/sisithefox/astrologybazi-api/resolve/main/README.md
15.9 kB
| title: AstrologyBazi API | |
| emoji: 🔮 | |
| colorFrom: yellow | |
| colorTo: red | |
| sdk: docker | |
| pinned: false | |
| license: mit | |
| # 🔮 AstrologyBazi API | |
| **Complete Eastern Mysticism API** - Professional BaZi (八字), Nine Flying Stars (九宫飞星), 28 Lunar Mansions (二十八星宿), and Chinese Calendar services. | |
| The **world's most comprehensive** Eastern fortune-telling API, powering [astrologybazi.com](https://astrologybazi.com) and fortune-telling SaaS platforms worldwide. | |
| ## Birth timezone and solar-clock context (local implementation, v1) | |
| The core `/calculate-bazi`, `/calculate-bazi-simple`, `/calculate-bazi-complete` | |
| and `/ai-interpretation` endpoints now accept optional `timezone`, `latitude`, | |
| `longitude`, `time_basis` and `fold`. The `/api/` aliases and analysis endpoints | |
| using `BaZiRequest` / `BaZiCompleteRequest` share the same calculation inputs. | |
| Other specialized request models have not been migrated to this contract. | |
| ```json | |
| { | |
| "birth_date": "1990-01-15", | |
| "birth_time": "09:30", | |
| "gender": "female", | |
| "is_lunar": false, | |
| "timezone": "Australia/Melbourne", | |
| "latitude": -37.8136, | |
| "longitude": 144.9631, | |
| "time_basis": "standard", | |
| "interpretation_level": "basic", | |
| "language": "en" | |
| } | |
| ``` | |
| `birth_date` and `birth_time` must be the ORIGINAL local birth record, before | |
| any client-side DST or solar correction. Do not send an already corrected | |
| clock together with `standard` or a solar mode, which would correct it twice. | |
| An explicit `gender` is required when using the new time-context fields. | |
| | time_basis | Day/hour clock | Required data | | |
| | --- | --- | --- | | |
| | omitted, no timezone | Legacy naive clock, unchanged | Existing inputs | | |
| | `civil` (default when timezone is supplied) | Original civil clock | IANA timezone | | |
| | `standard` | Civil clock minus historical DST | IANA timezone | | |
| | `mean_solar` | UTC plus longitude × 4 minutes/degree | IANA timezone, longitude | | |
| | `apparent_solar` | Mean solar clock plus NOAA equation-of-time approximation | IANA timezone, longitude | | |
| Time rules come from pinned `tzdata==2026.5`, including historical DST. | |
| Coordinates never silently determine an IANA timezone. Latitude is validated | |
| and recorded but does not enter the solar-clock formula. Solar modes preserve | |
| calendar-date rollover. Apparent solar time is an approximation; its response | |
| states the method and warns near day/hour boundaries. This is not a claim that | |
| one traditional clock convention is universally authoritative. | |
| For timezone-aware requests, year/month pillars and the existing sect-1 Yun | |
| calculation compare the absolute birth instant against the library's fixed | |
| UTC+08:00 JieQi table. Only day/hour pillars use the selected local clock. | |
| The existing sect-2 day-pillar / late-Zi convention is retained. `solar_date` | |
| continues to identify the original Gregorian birth date for age calculations. | |
| `num_dayun` now actually supplies the requested count, rather than silently | |
| stopping at the library's nine non-placeholder cycles. | |
| Responses include `time_context` in the chart (for `/ai-interpretation`, at | |
| `data.bazi_chart.time_context`). It records version, original and calculation | |
| clocks, UTC instant, timezone, DST/UTC offsets, correction minutes, solar-term | |
| reference clock, fold and warnings. A client requesting the new behavior MUST | |
| check `time_context.version == "bazi-time-context-v1"` and the echoed mode and | |
| birth inputs; an older deployment can otherwise ignore new JSON fields. | |
| Nonexistent local times during a forward clock jump are rejected. A repeated | |
| clock time requires `fold: 0` for its first occurrence or `fold: 1` for its | |
| second; never choose silently. Invalid contexts return HTTP 422 before chart | |
| or report generation. Legacy callers without new fields keep their previous | |
| clock convention and gender default for compatibility. | |
| Deployment order: deploy this backend and verify its OpenAPI and time-context | |
| responses before enabling the new request fields in website clients. Existing | |
| paid reports should remain cached; do not regenerate them silently. | |
| Verification (no external customer data or LLM calls): | |
| ```sh | |
| python -m pytest -q test_birth_time_context.py test_golden_charts.py \ | |
| test_canonical_strength_contract.py test_rule_contract.py \ | |
| test_dayun_rule_fixtures.py test_accuracy_validation.py | |
| ``` | |
| Sources: [Python zoneinfo](https://docs.python.org/3/library/zoneinfo.html), | |
| [NOAA solar-time equations](https://gml.noaa.gov/grad/solcalc/solareqns.PDF), | |
| and the pinned `lunar-python==1.4.8` `Yun` / `EightChar` implementation. | |
| ## 🌟 Features | |
| - ✅ **Accurate Calculations**: Uses traditional algorithms from `china-testing/bazi` | |
| - 🔐 **API Key Authentication**: Secure access control | |
| - 🌍 **Solar & Lunar Calendars**: Supports both Gregorian and Chinese lunar dates | |
| - 📊 **Complete Analysis**: Four Pillars, Day Master, Five Elements, Ten Gods, Hidden Stems | |
| - 🌟 **Nine Flying Stars (九宫飞星)**: Xuan Kong Feng Shui fortune analysis | |
| - 📅 **Chinese Calendar**: Daily almanac with auspicious activities | |
| - ⚡ **Fast & Reliable**: Hosted on Hugging Face Spaces | |
| - 📖 **Auto-Generated Docs**: Interactive API documentation at `/docs` | |
| ## 🚀 Quick Start | |
| ### Base URL | |
| ``` | |
| https://sisithefox-astrologybazi-api.hf.space | |
| ``` | |
| > **Note:** We're transitioning from the old URL. Both will work during migration period. | |
| ### Authentication | |
| All endpoints (except `/health`) require an API key in the request header: | |
| ```bash | |
| x-api-key: your_api_key_here | |
| ``` | |
| ### Example Request | |
| ```bash | |
| curl -X POST "https://sisithefox-astrologybazi-api.hf.space/calculate-bazi" \ | |
| -H "Content-Type: application/json" \ | |
| -H "x-api-key: your_api_key_here" \ | |
| -d '{ | |
| "birth_date": "1990-01-15", | |
| "birth_time": "08:30", | |
| "gender": "male", | |
| "is_lunar": false | |
| }' | |
| ``` | |
| ### Example Response | |
| ```json | |
| { | |
| "success": true, | |
| "data": { | |
| "bazi_chart": { | |
| "year": { | |
| "gan": "己", | |
| "zhi": "巳", | |
| "gan_element": "earth", | |
| "zhi_element": "fire", | |
| "pillar": "己巳" | |
| }, | |
| "month": { | |
| "gan": "丁", | |
| "zhi": "丑", | |
| "gan_element": "fire", | |
| "zhi_element": "earth", | |
| "pillar": "丁丑" | |
| }, | |
| "day": { | |
| "gan": "甲", | |
| "zhi": "子", | |
| "gan_element": "wood", | |
| "zhi_element": "water", | |
| "pillar": "甲子" | |
| }, | |
| "hour": { | |
| "gan": "戊", | |
| "zhi": "辰", | |
| "gan_element": "earth", | |
| "zhi_element": "earth", | |
| "pillar": "戊辰" | |
| } | |
| }, | |
| "day_master": { | |
| "gan": "甲", | |
| "element": "wood", | |
| "english": "Jia (Yang Wood)" | |
| }, | |
| "five_elements": { | |
| "wood": 1, | |
| "fire": 2, | |
| "earth": 4, | |
| "metal": 0, | |
| "water": 1 | |
| }, | |
| "ten_gods": { | |
| "heavenly_stems": ["财", "伤", "--", "比"], | |
| "earthly_branches": ["印", "杀", "杀", "官"] | |
| }, | |
| "hidden_stems": [...], | |
| "gender": "male", | |
| "solar_date": "1990-01-15", | |
| "lunar_date": "1989-12-19", | |
| "is_leap_month": false | |
| } | |
| } | |
| ``` | |
| ## 📡 API Endpoints | |
| ### 1. Health Check (No Auth Required) | |
| ```bash | |
| GET /health | |
| ``` | |
| **Response:** | |
| ```json | |
| { | |
| "status": "healthy", | |
| "service": "AstrologyBazi API", | |
| "version": "2.0.0" | |
| } | |
| ``` | |
| --- | |
| ### 2. Calculate BaZi (Full) | |
| ```bash | |
| POST /calculate-bazi | |
| POST /api/calculate-bazi | |
| ``` | |
| **Headers:** | |
| - `Content-Type: application/json` | |
| - `x-api-key: your_api_key_here` | |
| **Request Body:** | |
| ```json | |
| { | |
| "birth_date": "1990-01-15", | |
| "birth_time": "08:30", | |
| "gender": "male", | |
| "is_lunar": false | |
| } | |
| ``` | |
| **Parameters:** | |
| - `birth_date` (required): Birth date in `YYYY-MM-DD` format | |
| - `birth_time` (required): Birth time in `HH:MM` format (24-hour) | |
| - `gender` (optional): `"male"` or `"female"` (default: `"male"`) | |
| - `is_lunar` (optional): `true` for lunar calendar, `false` for solar (default: `false`) | |
| **Response:** Full BaZi analysis including: | |
| - Four Pillars (年月日时) | |
| - Day Master (日主) | |
| - Five Elements distribution (五行) | |
| - Ten Gods relationships (十神) | |
| - Hidden Stems (藏干) | |
| - Solar & Lunar dates | |
| --- | |
| ### 3. Calculate BaZi (Simplified) | |
| ```bash | |
| POST /calculate-bazi-simple | |
| ``` | |
| **Headers & Request Body:** Same as full calculation | |
| **Response:** Simplified version with only: | |
| - Four Pillars | |
| - Day Master | |
| - Five Elements | |
| Perfect for mobile apps and quick lookups. | |
| --- | |
| ### 4. Nine Flying Stars Analysis | |
| ```bash | |
| POST /api/nine-stars/analyze | |
| ``` | |
| **Headers:** | |
| - `Content-Type: application/json` | |
| - `x-api-key: your_api_key_here` | |
| **Request Body:** | |
| ```json | |
| { | |
| "date": "2025-12-11", | |
| "hour": 12 | |
| } | |
| ``` | |
| **Parameters:** | |
| - `date` (required): Target date in `YYYY-MM-DD` format | |
| - `hour` (optional): Hour of the day (0-23), default 12 (noon) | |
| **Response:** Complete Nine Flying Stars (九宫飞星) analysis: | |
| - Yearly/Monthly/Daily/Hourly flying stars (年月日时飞星) | |
| - Nine palace distribution (九宫分布) | |
| - Fortune analysis (吉凶分析) | |
| - Lucky/Unlucky directions (吉凶方位) | |
| **Example Response:** | |
| ```json | |
| { | |
| "success": true, | |
| "data": { | |
| "date": "2025-12-11", | |
| "hour": 12, | |
| "yearly_star": { | |
| "number": 2, | |
| "name": "二黑巨门星", | |
| "fortune": "凶" | |
| }, | |
| "monthly_star": { | |
| "number": 3, | |
| "name": "三碧禄存星", | |
| "fortune": "凶" | |
| }, | |
| "daily_star": { | |
| "number": 9, | |
| "name": "九紫右弼星", | |
| "fortune": "吉" | |
| }, | |
| "hourly_star": { | |
| "number": 6, | |
| "name": "六白武曲星", | |
| "fortune": "吉" | |
| }, | |
| "fortune_analysis": { | |
| "overall_score": 5.0, | |
| "overall_fortune": "平", | |
| "description": "吉凶参半,宜静观其变,稳中求进。", | |
| "lucky_directions": ["中", "西北", "南"], | |
| "avoid_directions": ["西", "东北", "北"] | |
| } | |
| } | |
| } | |
| ``` | |
| --- | |
| ### 5. Today's Nine Flying Stars | |
| ```bash | |
| GET /api/nine-stars/today?hour=12 | |
| ``` | |
| **Headers:** | |
| - `x-api-key: your_api_key_here` | |
| **Query Parameters:** | |
| - `hour` (optional): Hour of the day (0-23), default 12 | |
| **Response:** Same as `/api/nine-stars/analyze` but for today's date. | |
| --- | |
| ### 6. Chinese Calendar - Today | |
| ```bash | |
| GET /api/calendar/today | |
| ``` | |
| **No authentication required** - Public endpoint | |
| **Response:** Today's Chinese lunar calendar: | |
| - Solar & Lunar dates | |
| - Gan Zhi (干支) | |
| - Zodiac animal (生肖) | |
| - Almanac (黄历宜忌) | |
| - Solar terms (节气) | |
| - Festivals (节日) | |
| --- | |
| ### 7. Chinese Calendar - Specific Date | |
| ```bash | |
| GET /api/calendar/date/{date_str} | |
| ``` | |
| **Example:** | |
| ```bash | |
| GET /api/calendar/date/2025-12-11 | |
| ``` | |
| **No authentication required** - Public endpoint | |
| --- | |
| ### 8. 28 Lunar Mansions Analysis | |
| ```bash | |
| POST /api/28-constellations/analyze | |
| ``` | |
| **Headers:** | |
| - `Content-Type: application/json` | |
| - `x-api-key: your_api_key_here` | |
| **Request Body:** | |
| ```json | |
| { | |
| "date": "2025-12-11", | |
| "activities": ["嫁娶", "开市"] | |
| } | |
| ``` | |
| **Parameters:** | |
| - `date` (required): Target date in YYYY-MM-DD format | |
| - `activities` (optional): Activities to analyze | |
| **Response:** Complete 28 Lunar Mansions (二十八星宿) analysis: | |
| - Current constellation (当日星宿) | |
| - Four Symbols classification (四象: 青龙/朱雀/白虎/玄武) | |
| - Fortune level (1-5 stars) | |
| - Suitable/Avoid activities | |
| - Activity-specific recommendations | |
| --- | |
| ### 9. Today's Constellation | |
| ```bash | |
| GET /api/28-constellations/today | |
| ``` | |
| **Headers:** | |
| - `x-api-key: your_api_key_here` | |
| **Returns:** Today's 28 Lunar Mansions constellation info | |
| --- | |
| ### 10. Find Auspicious Dates | |
| ```bash | |
| POST /api/28-constellations/find-auspicious | |
| ``` | |
| **Headers:** | |
| - `Content-Type: application/json` | |
| - `x-api-key: your_api_key_here` | |
| **Request Body:** | |
| ```json | |
| { | |
| "activity": "嫁娶", | |
| "start_date": "2025-12-11", | |
| "end_date": "2026-01-11", | |
| "min_level": 4 | |
| } | |
| ``` | |
| **Parameters:** | |
| - `activity`: Activity name (e.g., "嫁娶", "开市", "安葬") | |
| - `start_date`: Start date | |
| - `end_date`: End date (max 1 year range) | |
| - `min_level`: Minimum fortune level (1-5), default 3 | |
| **Returns:** List of auspicious dates ranked by fortune level | |
| **Use Cases:** | |
| - Wedding date selection (择吉日嫁娶) | |
| - Business opening dates (开市择日) | |
| - Moving/relocation planning (搬家择日) | |
| --- | |
| ## 🔑 Getting API Access | |
| Contact **SisiTheFox** for API key access: | |
| - 📧 Email: contact@sisithefox.com | |
| - 🌐 Website: https://sisithefox.com | |
| ## 📚 Understanding the Response | |
| ### Four Pillars (四柱八字) | |
| Each pillar contains: | |
| - `gan`: Heavenly Stem (天干) - 10 stems (甲乙丙丁戊己庚辛壬癸) | |
| - `zhi`: Earthly Branch (地支) - 12 branches (子丑寅卯辰巳午未申酉戌亥) | |
| - `gan_element`: Element of the stem (wood/fire/earth/metal/water) | |
| - `zhi_element`: Dominant element of the branch | |
| - `pillar`: Combined Gan+Zhi (e.g., "甲子") | |
| ### Day Master (日主) | |
| The **most important element** in BaZi analysis: | |
| - Represents the person's core nature | |
| - Used as reference point for all relationships | |
| - Determines favorable/unfavorable elements | |
| ### Five Elements (五行) | |
| Distribution count of: | |
| - `wood` (木) | |
| - `fire` (火) | |
| - `earth` (土) | |
| - `metal` (金) | |
| - `water` (水) | |
| **Interpretation:** | |
| - Balanced elements (1-2 each) = harmonious life | |
| - Missing elements = areas of challenge | |
| - Excessive elements = areas of dominance | |
| ### Ten Gods (十神) | |
| Relationships between Day Master and other stems/branches: | |
| - 比劫 (Companion, Rob Wealth) | |
| - 食伤 (Eating God, Hurting Officer) | |
| - 财才 (Wealth, Talent) | |
| - 官杀 (Officer, Seven Killings) | |
| - 印枭 (Seal, Owl) | |
| ### Hidden Stems (藏干) | |
| Each Earthly Branch contains 1-3 hidden Heavenly Stems with varying strength: | |
| - **Main Qi (主气)**: Strongest influence (60-70%) | |
| - **Middle Qi (中气)**: Medium influence (20-30%) | |
| - **Residual Qi (余气)**: Weakest influence (10%) | |
| --- | |
| ## 🛠️ Technical Details | |
| ### Technology Stack | |
| - **Framework**: FastAPI 0.115.5 | |
| - **BaZi Library**: [china-testing/bazi](https://github.com/china-testing/bazi) | |
| - **Calendar**: lunar-python 1.6.0 | |
| - **Deployment**: Docker on Hugging Face Spaces | |
| ### Accuracy | |
| - ✅ Traditional algorithms verified against classical texts | |
| - ✅ Lunar-solar calendar conversion accurate from 1900-2100 | |
| - ✅ Timezone-aware calculations | |
| - ✅ Handles leap months correctly | |
| ### Rate Limits | |
| - **Free tier**: Contact for details | |
| - **Production usage**: Custom pricing available | |
| --- | |
| ## 💡 Use Cases | |
| ### 1. Face Reading App | |
| Combine with facial analysis AI to provide personalized fortune readings. | |
| ### 2. Astrology Platform | |
| Integrate with Western astrology (birth charts) for comprehensive analysis. | |
| ### 3. Fortune-Telling SaaS | |
| Build subscription services like: | |
| - astrologybazi.com (Eastern fortune-telling) | |
| - sisiastrology.com.au (Western astrology) | |
| ### 4. Mobile Apps | |
| Quick BaZi calculations for iOS/Android apps. | |
| ### 5. Wellness Coaching | |
| Use Five Elements balance for health/lifestyle recommendations. | |
| --- | |
| ## 🔗 Related APIs | |
| **Sisi API Suite:** | |
| - [Sisi Astrology API](https://huggingface.co/spaces/sisithefox/sisi-astrology-api) - Western birth charts | |
| - [Sisi PDF API](https://huggingface.co/spaces/sisithefox/sisithefox-pdf-api) - PDF generation & conversion | |
| --- | |
| ## 📄 License | |
| MIT License - Free for commercial use | |
| ## 🦊 About SisiTheFox | |
| **SisiTheFox** is building the world's most comprehensive mysticism SaaS ecosystem, combining: | |
| - Eastern systems: BaZi (八字), Ziwei (紫微), I-Ching (周易), Feng Shui (风水) | |
| - Western systems: Astrology, Tarot, Numerology | |
| - AI-powered interpretations | |
| - Beautiful user experiences | |
| **Mission**: Democratize ancient wisdom through modern technology. | |
| --- | |
| ## 🚀 API Status | |
| - ✅ **Live**: https://sisithefox-astrologybazi-api.hf.space | |
| - ✅ **Uptime**: 99.9%+ | |
| - ✅ **Response Time**: <500ms average | |
| - ✅ **Documentation**: https://sisithefox-astrologybazi-api.hf.space/docs | |
| --- | |
| ## 📞 Support | |
| Need help? Have questions? | |
| - 📧 Email: contact@sisithefox.com | |
| - 🌐 Website: https://astrologybazi.com | |
| - 📚 Docs: https://sisithefox-astrologybazi-api.hf.space/docs | |
| --- | |
| **Made with ❤️ by SisiTheFox | Powered by china-testing/bazi** | |