BaZi Flow (Annual/Monthly)
/api/v1/chinese/bazi/flowCalculate annual (Da Yun) and monthly flow pillars for predictive analysis. Returns interactions with natal chart and active stars for each time period.
Full URL
https://astro-api-1qnc.onrender.com/api/v1/chinese/bazi/flow⚠️ Rate Limit: 1 Year Maximum
To ensure performance, the year range is limited to 1 year per request. For multi-year forecasts, make sequential requests.
Response Modes
Fastest response. No interpretation text, minimal metadata.
Full details with interpretations and descriptions.
Includes calculation audit logs for troubleshooting.
Dictionary Response Mode
When dictionary_response: true, interactions and stars are returned as integer IDs instead of full objects. A root x_dict maps IDs to definitions.
Best Practice: Fetch the /dictionary endpoint once on app load, cache it, then use dictionary_response: false (default) for subsequent flow requests and resolve IDs client-side.
Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| year | integer | Yes | Birth year |
| month | integer | Yes | Birth month (1-12) |
| day | integer | Yes | Birth day (1-31) |
| hour | integer | Yes | Birth hour (0-23) |
| minute | integer | Yes | Birth minute (0-59) |
| city | string | Yes | City name (used for coordinate lookup via /geo/search) |
| lat | float | No | Latitude (-90 to 90). Optional: auto-resolved from city |
| lng | float | No | Longitude (-180 to 180). Optional: auto-resolved from city |
| sex | string | Yes | 'M' or 'F' |
| target_year | integer | Yes | Start year for forecast |
| target_year_end | integer | No | End year (max 1 year range). Default: target_year + 1 |
| mode | string | No | 'summary' (fastest), 'standard', or 'debug' |
| include | array | No | Whitelist fields: ['interactions', 'stars'] |
| dictionary_response | boolean | No | Return compact integer IDs with x_dict. Default: false |
Sample Code
import requests
import json
url = "https://astro-api-1qnc.onrender.com/api/v1/chinese/bazi/flow"
payload = {
"year": 1990,
"month": 5,
"day": 15,
"hour": 10,
"minute": 30,
"lat": 28.6139,
"lng": 77.2090,
"sex": "M",
"target_year": 2024,
"target_year_end": 2025, # Max 1 year range
"mode": "summary", # "summary" | "standard" | "debug"
"include": ["interactions"], # Optional whitelist
"dictionary_response": False # True for compact integer IDs
}
headers = {
"Content-Type": "application/json",
"x-api-key": "YOUR_API_KEY"
}
response = requests.post(url, headers=headers, json=payload)
print(response.json())Response Data
{
"target_year": 2024,
"target_year_end": 2025,
"years": [
{
"year": 2024,
"gan_zhi": "甲辰",
"gan": "甲",
"zhi": "辰",
"gan_pinyin": "jiǎ",
"zhi_pinyin": "chén",
"ten_god": "Direct Wealth",
"interactions": [1005, 2021], // Integer IDs
"stars": [4005], // Integer IDs
"months": [
{
"index": 1,
"name": "February 2024",
"gan_zhi": "丙寅",
"gan": "丙",
"zhi": "寅",
"ten_god": "Friend",
"interactions": [1012],
"stars": [4001, 4005]
},
{
"index": 2,
"name": "March 2024",
"gan_zhi": "丁卯",
"ten_god": "Rob Wealth",
"interactions": [2003, 3005],
"stars": []
}
// ... 12 months per year
]
}
],
// Only when dictionary_response: true
"x_dict": {
"1005": {
"type": "Stem Combination",
"name": "甲-己 Combination",
"stems": ["甲", "己"],
"transform_to": "Earth"
},
"2021": {
"type": "Branch Clash",
"name": "寅-申 Clash",
"branches": ["寅", "申"]
},
"4005": {
"name": "Tian Yi Nobleman",
"description": "The greatest protective star"
}
}
}