BaZi Flow (Annual/Monthly)

POST/api/v1/chinese/bazi/flow

Calculate 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://api.freeastroapi.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

summary

Fastest response. No interpretation text, minimal metadata.

standard

Full details with interpretations and descriptions.

debug

Includes calculation audit logs for troubleshooting.

Field Selection

If include is omitted, the response returns bothinteractions and stars by default.

If include is provided, it acts as a whitelist. For example,["interactions"] returns interactions only, and["stars"] returns stars only.

The preferred format is an array of strings. Legacy comma-separated strings such as"interactions,stars" are still accepted for backward compatibility.

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[string]	No	Optional whitelist for ['interactions', 'stars']. If omitted, both are returned by default. Legacy comma-separated strings are also accepted.
dictionary_response	boolean	No	Return compact integer IDs with x_dict. Default: false

Sample Code

curl -X POST "https://api.freeastroapi.com/api/v1/chinese/bazi/flow" \
 -H "Content-Type: application/json" \
 -H "x-api-key: YOUR_API_KEY" \
 -d '{
    "year": 1990,
    "month": 5,
    "day": 15,
    "hour": 10,
    "minute": 30,
    "lat": 28.6139,
    "lng": 77.2090,
    "sex": "M",
    "target_year": 2024,
    "mode": "summary"
}'

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

Related Endpoints

BaZi Chart

Natal chart calculation

Dictionary

ID to definition mappings