Chinese Annual Pillar API

A solar year's pillar against a chart: Tai Sui, relations and the twelve month pillars

POST/v1/chinese/annual

1 credit · Secret key (test or live) · getChineseAnnual

Request body

birth Birth required
- date string (date) required
  e.g. "1990-08-13"
- time string
  pattern ^([01]\d|2[0-3]):[0-5]\d(:[0-5]\d)?$ · e.g. "06:30"
- time_accuracy string
  With "unknown", lagna- and house-dependent fields are omitted and listed in warnings — never filled with a noon default.
  one of exact, approximate, unknown · default "exact"
- place Coordinates or object or object required
  Coordinates, a place_id from /v1/places/search, or a free-text query. A vague query returns 422 place_ambiguous with candidates; the API never guesses.
  
  One of:
  1. Coordinates
    Fields
    - latitude number required
      ≥ -90 · ≤ 90
    - longitude number required
      ≥ -180 · ≤ 180
    No other fields are accepted.
  2. object
    Fields
    - place_id string required
    No other fields are accepted.
  3. object
    Fields
    - query string required
      at least 2 characters · at most 120 characters
    No other fields are accepted.
- timezone string
  "auto" (from coordinates AND date), an IANA name, or a fixed offset like "+05:30".
  default "auto"
No other fields are accepted.
year integer required
≥ 1901 · ≤ 2099
time_basis string
one of clock, true_solar · default "clock"
zi_convention string
From 23:00, either the day pillar moves to the next day, or it stays and only the hour stem counts from the next day.
one of day_changes_at_23, late_zi · default "day_changes_at_23"
options object
- lang string required
  one of en, hi · default "en"
No other fields are accepted.

No other fields are accepted.

Response

JSON { data, meta, warnings }, where data is:

year integer required
from string (date-time) required
to string (date-time) required
pillar ChinesePillar required
- name string required
- chinese string required
- cycle_number integer required
  ≥ 1 · ≤ 60
- stem object required
  Fields
  - id string required
  - chinese string required
  - element string required
  - element_name string required
  - polarity string required
    one of yang, yin
  - ten_god object
    Fields
    id string required
    name string required
- branch object required
  Fields
  - id string required
  - chinese string required
  - animal string required
  - animal_name string required
  - element string required
  - element_name string required
  - polarity string required
    one of yang, yin
  - hidden_stems array of object required
    Fields
    id string required
    chinese string required
    element string required
    element_name string required
    polarity string required
    one of yang, yin
    
    ten_god object
    Fields
    id string required
    name string required
- nayin object required
  Fields
  - chinese string required
  - name string required
tai_sui array of string required
relations array of object required
- pillar string required
- branch_relations array of object required
  Fields
  - id string required
  - kind string
    one of harmony, conflict
  - element string
- stem_relation object or null required
  One of:
  1. object
    Fields
    - id string required
    - kind string
      one of harmony, conflict
    - element string
  2. null
months array of object required
- month integer required
- from string (date-time) required
- pillar ChinesePillar required
  Fields
  - name string required
  - chinese string required
  - cycle_number integer required
    ≥ 1 · ≤ 60
  - stem object required
    Fields
    id string required
    chinese string required
    element string required
    element_name string required
    polarity string required
    one of yang, yin
    
    ten_god object
    Fields
    id string required
    name string required
  - branch object required
    Fields
    id string required
    chinese string required
    animal string required
    animal_name string required
    element string required
    element_name string required
    polarity string required
    one of yang, yin
    
    hidden_stems array of object required
    Fields
    id string required
    chinese string required
    element string required
    element_name string required
    polarity string required
    one of yang, yin
    
    ten_god object
    Fields
    id string required
    name string required
  - nayin object required
    Fields
    chinese string required
    name string required

Errors: 400, 401, 403, 404, 422, 429, 500. See error codes.

Example request

curl -X POST 'https://api.astrologics.in/v1/chinese/annual' \
  -H 'Authorization: Bearer al_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"birth":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}},"year":2026}'

Node.js

const res = await fetch("https://api.astrologics.in/v1/chinese/annual", {
  method: "POST",
  headers: { Authorization: "Bearer al_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "birth": {
      "date": "1990-08-13",
      "time": "06:30",
      "place": {
        "latitude": 28.6139,
        "longitude": 77.209
      }
    },
    "year": 2026
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));

Python

import json
import urllib.error
import urllib.request

body = {
    "birth": {
        "date": "1990-08-13",
        "time": "06:30",
        "place": {
            "latitude": 28.6139,
            "longitude": 77.209,
        },
    },
    "year": 2026,
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/chinese/annual",
    method="POST",
    headers={"Authorization": "Bearer al_test_YOUR_KEY", "Content-Type": "application/json"},
    data=json.dumps(body).encode(),
)
try:
    with urllib.request.urlopen(req) as res:
        print(json.dumps(json.load(res), indent=2, ensure_ascii=False))
except urllib.error.HTTPError as err:
    print(err.code, err.read().decode())

PHP

<?php
$ch = curl_init('https://api.astrologics.in/v1/chinese/annual');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer al_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"birth":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}},"year":2026}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;

Example response

200 OK · 22,460 characters

{
  "data": {
    "year": 2026,
    "from": "2026-02-03T20:01:54.541Z",
    "to": "2027-02-04T01:46:24.431Z",
    "pillar": {
      "name": "Bing Wu",
      "chinese": "丙午",
      "cycle_number": 43,
      "stem": {
        "id": "bing",
        "chinese": "丙",
        "element": "fire",
        "element_name": "Fire",
        "polarity": "yang",
        "ten_god": {
          "id": "qi_sha",
          "name": "Seven Killings"
        }
      },
      "branch": {
        "id": "wu",
        "chinese": "午",
        "animal": "horse",
        "animal_name": "Horse",
        "element": "fire",
        "element_name": "Fire",
        "polarity": "yang",
        "hidden_stems": [
          {
            "id": "ding",
            "chinese": "丁",
            "element": "fire",
            "element_name": "Fire",
            "polarity": "yin",
            "ten_god": {
              "id": "zheng_guan",
              "name": "Direct Officer"
            }
          },
          {
            "id": "ji",
            "chinese": "己",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yin",
            "ten_god": {
              "id": "zheng_yin",
              "name": "Direct Resource"
            }
          }
        ]
      },
      "nayin": {
        "chinese": "天河水",
        "name": "Water of the Heavenly River"
      }
    },
    "tai_sui": [
      "same",
      "self_punishment"
    ],
    "relations": [
      {
        "pillar": "year",
        "branch_relations": [
          {
            "id": "same"
          },
          {
            "id": "self_punishment",
            "kind": "conflict"
          }
        ],
        "stem_relation": null
      },
      {
        "pillar": "month",
        "branch_relations": [],
        "stem_relation": null
      },
      {
        "pillar": "day",
        "branch_relations": [
          {
            "id": "three_harmony",
            "kind": "harmony",
            "element": "fire"
          }
        ],
        "stem_relation": null
      },
      {
        "pillar": "hour",
        "branch_relations": [
          {
            "id": "destruction",
            "kind": "conflict"
          }
        ],
        "stem_relation": null
      }
    ],
    "months": [
      {
        "month": 1,
        "from": "2026-02-03T20:01:54.541Z",
        "pillar": {
          "name": "Geng Yin",
          "chinese": "庚寅",
          "cycle_number": 27,
          "stem": {
            "id": "geng",
            "chinese": "庚",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yang",
            "ten_god": {
              "id": "bi_jian",
              "name": "Friend"
            }
          },
          "branch": {
            "id": "yin",
            "chinese": "寅",
            "animal": "tiger",
            "animal_name": "Tiger",
            "element": "wood",
            "element_name": "Wood",
            "polarity": "yang",
            "hidden_stems": [
              {
                "id": "jia",
                "chinese": "甲",
                "element": "wood",
                "element_name": "Wood",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_cai",
                  "name": "Indirect Wealth"
                }
              },
              {
                "id": "bing",
                "chinese": "丙",
                "element": "fire",
                "element_name": "Fire",
                "polarity": "yang",
                "ten_god": {
                  "id": "qi_sha",
                  "name": "Seven Killings"
                }
              },
              {
                "id": "wu",
                "chinese": "戊",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_yin",
                  "name": "Indirect Resource"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "松柏木",
            "name": "Pine and Cypress Wood"
          }
        }
      },
      {
        "month": 2,
        "from": "2026-03-05T13:58:43.971Z",
        "pillar": {
          "name": "Xin Mao",
          "chinese": "辛卯",
          "cycle_number": 28,
          "stem": {
            "id": "xin",
            "chinese": "辛",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yin",
            "ten_god": {
              "id": "jie_cai",
              "name": "Rob Wealth"
            }
          },
          "branch": {
            "id": "mao",
            "chinese": "卯",
            "animal": "rabbit",
            "animal_name": "Rabbit",
            "element": "wood",
            "element_name": "Wood",
            "polarity": "yin",
            "hidden_stems": [
              {
                "id": "yi",
                "chinese": "乙",
                "element": "wood",
                "element_name": "Wood",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_cai",
                  "name": "Direct Wealth"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "松柏木",
            "name": "Pine and Cypress Wood"
          }
        }
      },
      {
        "month": 3,
        "from": "2026-04-04T18:39:59.161Z",
        "pillar": {
          "name": "Ren Chen",
          "chinese": "壬辰",
          "cycle_number": 29,
          "stem": {
            "id": "ren",
            "chinese": "壬",
            "element": "water",
            "element_name": "Water",
            "polarity": "yang",
            "ten_god": {
              "id": "shi_shen",
              "name": "Eating God"
            }
          },
          "branch": {
            "id": "chen",
            "chinese": "辰",
            "animal": "dragon",
            "animal_name": "Dragon",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yang",
            "hidden_stems": [
              {
                "id": "wu",
                "chinese": "戊",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_yin",
                  "name": "Indirect Resource"
                }
              },
              {
                "id": "yi",
                "chinese": "乙",
                "element": "wood",
                "element_name": "Wood",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_cai",
                  "name": "Direct Wealth"
                }
              },
              {
                "id": "gui",
                "chinese": "癸",
                "element": "water",
                "element_name": "Water",
                "polarity": "yin",
                "ten_god": {
                  "id": "shang_guan",
                  "name": "Hurting Officer"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "长流水",
            "name": "Long-Flowing Water"
          }
        }
      },
      {
        "month": 4,
        "from": "2026-05-05T11:49:09.475Z",
        "pillar": {
          "name": "Gui Si",
          "chinese": "癸巳",
          "cycle_number": 30,
          "stem": {
            "id": "gui",
            "chinese": "癸",
            "element": "water",
            "element_name": "Water",
            "polarity": "yin",
            "ten_god": {
              "id": "shang_guan",
              "name": "Hurting Officer"
            }
          },
          "branch": {
            "id": "si",
            "chinese": "巳",
            "animal": "snake",
            "animal_name": "Snake",
            "element": "fire",
            "element_name": "Fire",
            "polarity": "yin",
            "hidden_stems": [
              {
                "id": "bing",
                "chinese": "丙",
                "element": "fire",
                "element_name": "Fire",
                "polarity": "yang",
                "ten_god": {
                  "id": "qi_sha",
                  "name": "Seven Killings"
                }
              },
              {
                "id": "geng",
                "chinese": "庚",
                "element": "metal",
                "element_name": "Metal",
                "polarity": "yang",
                "ten_god": {
                  "id": "bi_jian",
                  "name": "Friend"
                }
              },
              {
                "id": "wu",
                "chinese": "戊",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_yin",
                  "name": "Indirect Resource"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "长流水",
            "name": "Long-Flowing Water"
          }
        }
      },
      {
        "month": 5,
        "from": "2026-06-05T15:48:59.457Z",
        "pillar": {
          "name": "Jia Wu",
          "chinese": "甲午",
          "cycle_number": 31,
          "stem": {
            "id": "jia",
            "chinese": "甲",
            "element": "wood",
            "element_name": "Wood",
            "polarity": "yang",
            "ten_god": {
              "id": "pian_cai",
              "name": "Indirect Wealth"
            }
          },
          "branch": {
            "id": "wu",
            "chinese": "午",
            "animal": "horse",
            "animal_name": "Horse",
            "element": "fire",
            "element_name": "Fire",
            "polarity": "yang",
            "hidden_stems": [
              {
                "id": "ding",
                "chinese": "丁",
                "element": "fire",
                "element_name": "Fire",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_guan",
                  "name": "Direct Officer"
                }
              },
              {
                "id": "ji",
                "chinese": "己",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_yin",
                  "name": "Direct Resource"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "砂中金",
            "name": "Gold in the Sand"
          }
        }
      },
      {
        "month": 6,
        "from": "2026-07-07T01:57:22.386Z",
        "pillar": {
          "name": "Yi Wei",
          "chinese": "乙未",
          "cycle_number": 32,
          "stem": {
            "id": "yi",
            "chinese": "乙",
            "element": "wood",
            "element_name": "Wood",
            "polarity": "yin",
            "ten_god": {
              "id": "zheng_cai",
              "name": "Direct Wealth"
            }
          },
          "branch": {
            "id": "wei",
            "chinese": "未",
            "animal": "goat",
            "animal_name": "Goat",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yin",
            "hidden_stems": [
              {
                "id": "ji",
                "chinese": "己",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_yin",
                  "name": "Direct Resource"
                }
              },
              {
                "id": "ding",
                "chinese": "丁",
                "element": "fire",
                "element_name": "Fire",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_guan",
                  "name": "Direct Officer"
                }
              },
              {
                "id": "yi",
                "chinese": "乙",
                "element": "wood",
                "element_name": "Wood",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_cai",
                  "name": "Direct Wealth"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "砂中金",
            "name": "Gold in the Sand"
          }
        }
      },
      {
        "month": 7,
        "from": "2026-08-07T11:42:56.663Z",
        "pillar": {
          "name": "Bing Shen",
          "chinese": "丙申",
          "cycle_number": 33,
          "stem": {
            "id": "bing",
            "chinese": "丙",
            "element": "fire",
            "element_name": "Fire",
            "polarity": "yang",
            "ten_god": {
              "id": "qi_sha",
              "name": "Seven Killings"
            }
          },
          "branch": {
            "id": "shen",
            "chinese": "申",
            "animal": "monkey",
            "animal_name": "Monkey",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yang",
            "hidden_stems": [
              {
                "id": "geng",
                "chinese": "庚",
                "element": "metal",
                "element_name": "Metal",
                "polarity": "yang",
                "ten_god": {
                  "id": "bi_jian",
                  "name": "Friend"
                }
              },
              {
                "id": "ren",
                "chinese": "壬",
                "element": "water",
                "element_name": "Water",
                "polarity": "yang",
                "ten_god": {
                  "id": "shi_shen",
                  "name": "Eating God"
                }
              },
              {
                "id": "wu",
                "chinese": "戊",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_yin",
                  "name": "Indirect Resource"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "山下火",
            "name": "Fire Under the Mountain"
          }
        }
      },
      {
        "month": 8,
        "from": "2026-09-07T14:41:44.296Z",
        "pillar": {
          "name": "Ding You",
          "chinese": "丁酉",
          "cycle_number": 34,
          "stem": {
            "id": "ding",
            "chinese": "丁",
            "element": "fire",
            "element_name": "Fire",
            "polarity": "yin",
            "ten_god": {
              "id": "zheng_guan",
              "name": "Direct Officer"
            }
          },
          "branch": {
            "id": "you",
            "chinese": "酉",
            "animal": "rooster",
            "animal_name": "Rooster",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yin",
            "hidden_stems": [
              {
                "id": "xin",
                "chinese": "辛",
                "element": "metal",
                "element_name": "Metal",
                "polarity": "yin",
                "ten_god": {
                  "id": "jie_cai",
                  "name": "Rob Wealth"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "山下火",
            "name": "Fire Under the Mountain"
          }
        }
      },
      {
        "month": 9,
        "from": "2026-10-08T06:29:58.055Z",
        "pillar": {
          "name": "Wu Xu",
          "chinese": "戊戌",
          "cycle_number": 35,
          "stem": {
            "id": "wu",
            "chinese": "戊",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yang",
            "ten_god": {
              "id": "pian_yin",
              "name": "Indirect Resource"
            }
          },
          "branch": {
            "id": "xu",
            "chinese": "戌",
            "animal": "dog",
            "animal_name": "Dog",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yang",
            "hidden_stems": [
              {
                "id": "wu",
                "chinese": "戊",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_yin",
                  "name": "Indirect Resource"
                }
              },
              {
                "id": "xin",
                "chinese": "辛",
                "element": "metal",
                "element_name": "Metal",
                "polarity": "yin",
                "ten_god": {
                  "id": "jie_cai",
                  "name": "Rob Wealth"
                }
              },
              {
                "id": "ding",
                "chinese": "丁",
                "element": "fire",
                "element_name": "Fire",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_guan",
                  "name": "Direct Officer"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "平地木",
            "name": "Wood of the Plain"
          }
        }
      },
      {
        "month": 10,
        "from": "2026-11-07T09:52:33.362Z",
        "pillar": {
          "name": "Ji Hai",
          "chinese": "己亥",
          "cycle_number": 36,
          "stem": {
            "id": "ji",
            "chinese": "己",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yin",
            "ten_god": {
              "id": "zheng_yin",
              "name": "Direct Resource"
            }
          },
          "branch": {
            "id": "hai",
            "chinese": "亥",
            "animal": "pig",
            "animal_name": "Pig",
            "element": "water",
            "element_name": "Water",
            "polarity": "yin",
            "hidden_stems": [
              {
                "id": "ren",
                "chinese": "壬",
                "element": "water",
                "element_name": "Water",
                "polarity": "yang",
                "ten_god": {
                  "id": "shi_shen",
                  "name": "Eating God"
                }
              },
              {
                "id": "jia",
                "chinese": "甲",
                "element": "wood",
                "element_name": "Wood",
                "polarity": "yang",
                "ten_god": {
                  "id": "pian_cai",
                  "name": "Indirect Wealth"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "平地木",
            "name": "Wood of the Plain"
          }
        }
      },
      {
        "month": 11,
        "from": "2026-12-07T02:52:47.191Z",
        "pillar": {
          "name": "Geng Zi",
          "chinese": "庚子",
          "cycle_number": 37,
          "stem": {
            "id": "geng",
            "chinese": "庚",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yang",
            "ten_god": {
              "id": "bi_jian",
              "name": "Friend"
            }
          },
          "branch": {
            "id": "zi",
            "chinese": "子",
            "animal": "rat",
            "animal_name": "Rat",
            "element": "water",
            "element_name": "Water",
            "polarity": "yang",
            "hidden_stems": [
              {
                "id": "gui",
                "chinese": "癸",
                "element": "water",
                "element_name": "Water",
                "polarity": "yin",
                "ten_god": {
                  "id": "shang_guan",
                  "name": "Hurting Officer"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "壁上土",
            "name": "Earth on the Wall"
          }
        }
      },
      {
        "month": 12,
        "from": "2027-01-05T14:10:07.756Z",
        "pillar": {
          "name": "Xin Chou",
          "chinese": "辛丑",
          "cycle_number": 38,
          "stem": {
            "id": "xin",
            "chinese": "辛",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yin",
            "ten_god": {
              "id": "jie_cai",
              "name": "Rob Wealth"
            }
          },
          "branch": {
            "id": "chou",
            "chinese": "丑",
            "animal": "ox",
            "animal_name": "Ox",
            "element": "earth",
            "element_name": "Earth",
            "polarity": "yin",
            "hidden_stems": [
              {
                "id": "ji",
                "chinese": "己",
                "element": "earth",
                "element_name": "Earth",
                "polarity": "yin",
                "ten_god": {
                  "id": "zheng_yin",
                  "name": "Direct Resource"
                }
              },
              {
                "id": "gui",
                "chinese": "癸",
                "element": "water",
                "element_name": "Water",
                "polarity": "yin",
                "ten_god": {
                  "id": "shang_guan",
                  "name": "Hurting Officer"
                }
              },
              {
                "id": "xin",
                "chinese": "辛",
                "element": "metal",
                "element_name": "Metal",
                "polarity": "yin",
                "ten_god": {
                  "id": "jie_cai",
                  "name": "Rob Wealth"
                }
              }
            ]
          },
          "nayin": {
            "chinese": "壁上土",
            "name": "Earth on the Wall"
          }
        }
      }
    ]
  },
  "meta": {
    "request_id": "req_example",
    "api_version": "v1",
    "engine_version": "2026.10.10",
    "mode": "live",
    "credits_charged": 1
  },
  "warnings": []
}

Try it

Test key (optional)

Leave empty to use the shared demo key (limited). Test keys only: never charged. Kept in this browser tab and sent through this site to the API. Create one

Body (JSON)

{
  "birth": {
    "date": "1990-08-13",
    "time": "06:30",
    "place": {
      "latitude": 28.6139,
      "longitude": 77.209
    }
  },
  "year": 2026
}

Chinese Annual Pillar API

Request body

Response

Example request

Example response

More in Chinese