---
title: "BaZi Ten Gods Analysis"
method: POST
path: "/chinese/bazi/ten-gods"
tags: ["chinese"]
---

# BaZi Ten Gods Analysis

`POST /chinese/bazi/ten-gods`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/chinese/bazi/ten-gods`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-OpenEphemeris-API-Key`
  - API key in header `X-API-Key`
  - API key in header `X-Service-Key`

Calculate the Ten Gods (十神 Shí Shén) for a BaZi chart relative to the Day Master. Returns the Ten God label, Chinese name, category, and hidden stem Ten Gods for all four pillars.

The Ten Gods describe the nature of each element in the chart relative to the self (Day Master): Friend, Rob Wealth, Eating God, Hurting Officer, Indirect Wealth, Direct Wealth, Seven Killings, Direct Officer, Indirect Resource, Direct Resource.

**Metering**: 3 units per call.

## Request body

- BaZiRequest: Request body for a BaZi (Four Pillars) calculation.
  - `day` integer, required: Birth day of month (1–31).
  - `day_boundary` 'zi_hour' | 'midnight': Day-pillar boundary convention. zi_hour rolls the day pillar at 23:00 (start of the Zi hour); midnight rolls it at 00:00.
  - `format` 'json' | 'llm': Response format: json | llm.
  - `hour` integer: Birth hour (0–23). Defaults to 12 (noon). Chinese hours (shí) are 2-hour blocks, so precision within a 2-hour window is sufficient.
  - `latitude` number, double: Birth latitude in decimal degrees (north positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
  - `longitude` number, double: Birth longitude in decimal degrees (east positive). Required when true_solar_time is true. Otherwise optional: when BOTH coordinates are supplied and in range they resolve the birth timezone used to frame the solar-term boundary comparison (see `timezone`), which can change the year or month pillar for a birth near a boundary. Half a pair is still accepted and ignored.
  - `minute` integer: Birth minute (0–59). Defaults to 0, which reproduces the integer-hour behaviour exactly. Chinese hours (shí) are 2-hour blocks starting on odd hours, so a minute alone never moves the hour branch — it becomes load-bearing under true_solar_time, where the correction of up to ~±45 minutes is added to hour+minute/60 before the block and the 23:00 zi-hour tests are applied, and in the solar-term frame, where it shifts the birth instant by up to 59 minutes and can flip a Li Chun or Jié comparison for a birth within an hour of one.
  - `month` integer, required: Birth month (1–12).
  - `timezone` TimezoneInput: Timezone input using IANA names or UTC offsets.
    - `fold_preference` 'earlier' | 'later': Which occurrence to use when the naive local datetime falls in a fall-back fold (a repeated hour): 'earlier' (default — first occurrence) or 'later'. Only meaningful for naive datetimes; the response reports datetime_status=ambiguous_fold either way so the ambiguity can be surfaced to the user.
    - `iana_name` string: IANA timezone name
    - `time_standard` 'auto' | 'standard' | 'daylight': How to interpret a naive local datetime when this zone is applied. 'auto' (default): resolve through the historical-correction overlay where one covers the region/era, then IANA tzdata. 'standard': force the zone's standard (non-daylight) offset — for callers who KNOW the recorded time was standard time regardless of what tzdata believes. 'daylight': force standard+1h. Forcing either marks the resolution tz_confidence=client_override. Ignored when the datetime carries its own Z/±HH:MM suffix or when utc_offset is used.
    - `utc_offset` number: UTC offset in hours
  - `true_solar_time` boolean: When true, the birth wall clock is converted to local apparent (true) solar time before the pillars are derived: the longitude correction relative to the timezone's standard meridian plus the equation of time. The correction can move the day - and therefore the day pillar and, through it, the hour stem - as well as the hour branch. The year and month pillars are compared at the true birth INSTANT and are unaffected by the correction, which transforms a clock reading rather than moving the birth. Requires latitude and longitude.
  - `year` integer, required: Gregorian birth year.
  - `year_boundary` 'lichun' | 'cny': Year-pillar boundary convention. lichun rolls the year pillar at the Lichun (立春) solar term, around 4 February; cny rolls it at Chinese New Year.

## Response `200`

Ten Gods for all four pillars.

- BaZiTenGodsResponse
  - `calculation_metadata` object: Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it.
  - `day_master` object, required
    - `element` string
    - `polarity` string
    - `stem` string
  - `pillars` BaZiPillarTenGods[], required
    - `hidden_ten_gods` object[], required
      - `hidden_stem` BaZiHiddenStemEntry, required
        - `chinese` string, required: Chinese character, e.g. '癸'
        - `element` 'Wood' | 'Fire' | 'Earth' | 'Metal' | 'Water', required
        - `name` string, required: Romanised stem name, e.g. 'Gui'
        - `polarity` 'Yang' | 'Yin', required
        - `strength` 'main' | 'secondary' | 'residual', required
        - `weight` number, double, required
      - `ten_god` BaZiTenGodEntry, required
        - `category` 'companion' | 'output' | 'wealth' | 'power' | 'resource', required
        - `chinese` string, required: Chinese characters, e.g. '正官'
        - `name` string, required: English name, e.g. 'Direct Officer'
        - `pinyin` string, required
    - `pillar` 'year' | 'month' | 'day' | 'hour', required
    - `visible_ten_god` BaZiTenGodEntry
      - `category` 'companion' | 'output' | 'wealth' | 'power' | 'resource', required
      - `chinese` string, required: Chinese characters, e.g. '正官'
      - `name` string, required: English name, e.g. 'Direct Officer'
      - `pinyin` string, required
  - `success` boolean

## Other responses

- `422`: Validation error.

---

[API](https://skmtc.dev/openephemeris/apis/open-ephemeris-api.md) · [All operations](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/llms.txt) · [OpenAPI document](https://skmtc.dev/openephemeris/apis/open-ephemeris-api/revisions/d195a769cb89?raw)