Back to Docs

BaZi Flow (Annual/Monthly)

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

Field
year
Type
integer
Required
Yes
Description
Birth year (1 or greater).
Field
month
Type
integer
Required
Yes
Description
Birth month (1-12)
Field
day
Type
integer
Required
Yes
Description
Birth day (1-31)
Field
hour
Type
integer
Required
No
Description
Birth hour (0-23). Default: 12.
Field
minute
Type
integer
Required
No
Description
Birth minute (0-59). Default: 0.
Field
city
Type
string
Required
No
Description
City used for coordinate lookup. Supply either a resolvable city or both lat and lng.
Field
lat
Type
number
Required
No
Description
Latitude (-90 to 90). Required with lng when city is omitted.
Field
lng
Type
number
Required
No
Description
Longitude (-180 to 180). Required with lat when city is omitted.
Field
sex
Type
"M" | "F"
Required
No
Description
Affects luck-cycle direction. Case-insensitive. Default: M.
Field
time_standard
Type
string
Required
No
Description
civil, true_solar, or true_solar_absolute. This setting changes the natal reference chart. Default: civil.
Field
tz_str
Type
string
Required
No
Description
IANA timezone name or AUTO. Default: AUTO.
Field
target_year
Type
integer
Required
Yes
Description
Start year for forecast
Field
target_year_end
Type
integer
Required
No
Description
Must equal target_year when supplied. Default: target_year.
Field
include_pinyin
Type
boolean
Required
No
Description
Include Pinyin fields. Default: true.
Field
mode
Type
string
Required
No
Description
summary, standard, or debug. Default: summary.
Field
include
Type
string[] | string
Required
No
Description
Whitelist interactions and/or stars. Arrays are preferred; comma-separated strings remain supported.
Field
exclude
Type
string[] | string
Required
No
Description
Exclude interactions, stars, or baseline_interactions. Arrays and comma-separated strings are accepted.
Field
dictionary_response
Type
boolean
Required
No
Description
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",
    "time_standard": "civil",
    "tz_str": "Asia/Kolkata",
    "target_year": 2024,
    "mode": "summary"
}'

Response Data

{
  "years": [
    {
      "year": 2024,
      "gan_zhi": "甲辰",
      "gan": "甲",
      "zhi": "辰",
      "age": 35,
      "gan_pinyin": "jiǎ",
      "zhi_pinyin": "chén",
      "active_luck": {
        "gan_zhi": "甲申",
        "start_year": 2017,
        "end_year": 2026
      },
      "interactions": [
        {
          "id": "stem_clash_year_luck",
          "type": "Stem Clash",
          "scope": "luck_overlay",
          "pillars": ["year", "luck"],
          "stems": ["庚", "甲"]
        }
      ],
      "months": [
        {
          "index": 0,
          "gan_zhi": "丙寅",
          "gan": "丙",
          "zhi": "寅",
          "gan_pinyin": "bǐng",
          "zhi_pinyin": "yín",
          "interactions": [
            {
              "id": "stem_combo_month_monthly_flow",
              "type": "Stem Combination",
              "scope": "monthly_overlay",
              "pillars": ["month", "monthly_flow"],
              "stems": ["辛", "丙"],
              "transform_to": "Water"
            }
          ]
        }
      ]
    }
  ]
}

Related Endpoints

BaZi Chart

Natal chart calculation

Dictionary

ID to definition mappings