Spaces:

sisithefox
/

astrologybazi-api

Running

Fix BaZi timezone and historical daylight-saving calculation

40d3e55 21 days ago

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 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.

{
  "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):

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, NOAA solar-time equations, 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:

x-api-key: your_api_key_here

Example Request

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

{
  "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)

GET /health

Response:

{
  "status": "healthy",
  "service": "AstrologyBazi API",
  "version": "2.0.0"
}

2. Calculate BaZi (Full)

POST /calculate-bazi
POST /api/calculate-bazi

Headers:

Content-Type: application/json
x-api-key: your_api_key_here

Request Body:

{
  "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)

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

POST /api/nine-stars/analyze

Headers:

Content-Type: application/json
x-api-key: your_api_key_here

Request Body:

{
  "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:

{
  "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

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

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

GET /api/calendar/date/{date_str}

Example:

GET /api/calendar/date/2025-12-11

No authentication required - Public endpoint

8. 28 Lunar Mansions Analysis

POST /api/28-constellations/analyze

Headers:

Content-Type: application/json
x-api-key: your_api_key_here

Request Body:

{
  "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

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

POST /api/28-constellations/find-auspicious

Headers:

Content-Type: application/json
x-api-key: your_api_key_here

Request Body:

{
  "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
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 - Western birth charts
Sisi 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