---
title: "BaZi Annual Pillar (Liu Nian)"
method: POST
path: "/chinese/bazi/annual-pillar"
tags: ["chinese"]
---

# BaZi Annual Pillar (Liu Nian)

`POST /chinese/bazi/annual-pillar`

## Request

- Base URL: `https://api.openephemeris.com`
- URL: `https://api.openephemeris.com/chinese/bazi/annual-pillar`
- 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 Heavenly Stem and Earthly Branch for any given Gregorian year (Liu Nian 流年 annual pillar). Optionally returns the NaYin resonance element.

**Metering**: 3 units per call.

## Request body

- BaZiAnnualPillarRequest: Request for the Liu Nian (流年) annual pillar. Supply year alone for the sexagenary label of that Gregorian year, or add month/day (and optionally hour) to classify a specific moment under the chosen year_boundary.
  - `day` integer: Optional day of month. When supplied together with month, the moment is classified under year_boundary and the resolved BaZi year is returned. Must be supplied together with month.
  - `hour` integer: Optional hour (0–23), only meaningful when month and day are supplied. Defaults to 12 (noon).
  - `month` integer: Optional month (1–12). When supplied together with day, the moment is classified under year_boundary and the resolved BaZi year is returned. Must be supplied together with day.
  - `year` integer, required: Gregorian year for the Liu Nian calculation. When month and day are supplied, the response echoes the resolved BaZi year, which may differ from this value.
  - `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`

Annual pillar stem, branch, and NaYin.

- BaZiAnnualPillarResponse
  - `animal` string, required
  - `branch` string, required
  - `branch_chinese` string, required
  - `calculation_metadata` object: Optional calculation provenance metadata (timing, engine flags, ayanamsa, etc.). Free-form; present when the handler attaches it. Present when month and day were supplied, i.e. when a specific moment was classified under year_boundary. Absent for a year-only request, which resolves no moment and therefore has no provenance to report.
  - `element` string, required
  - `nayin` object, required
    - `element` string
    - `image` string
    - `image_chinese` string
  - `polarity` 'Yang' | 'Yin', required
  - `sexagenary_index` integer, required
  - `stem` string, required
  - `stem_chinese` string, required
  - `success` boolean
  - `year` integer, required

## 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)