Bazi Four Pillars API

The four pillars with hidden stems, ten gods, nayin and element counts

POST/v1/chinese/bazi

2 credits · Secret key (test or live) · getBazi

The year turns at Li Chun and the month at each jie. Clock or true solar time, and how the Zi hour is treated, are options. With an unknown birth time, the hour pillar is null. No reading of day-master strength is given, because schools differ.

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.
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:

moment string (date-time) required
time_known boolean required
time_basis string or null required
One of:
1. string
2. null
zi_convention string required
zi_hour string or null required
One of:
1. string
2. null
solar_year integer required
pillars object required
- year 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
- month 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
- day 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
- hour ChinesePillar or null required
  One of:
  1. ChinesePillar
    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
  2. null
day_master object required
- id string required
- chinese string required
- element string required
- element_name string required
- polarity string required
  one of yang, yin
elements object required
- visible object required
  Fields
  - wood integer required
  - fire integer required
  - earth integer required
  - metal integer required
  - water integer required
- hidden object required
  Fields
  - wood integer required
  - fire integer required
  - earth integer required
  - metal integer required
  - water integer required

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

Example request

curl -X POST 'https://api.astrologics.in/v1/chinese/bazi' \
  -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}}}'

Node.js

const res = await fetch("https://api.astrologics.in/v1/chinese/bazi", {
  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
      }
    }
  }),
});
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,
        },
    },
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/chinese/bazi",
    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/bazi');
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}}}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;

Example response

200 OK · 6,133 characters

{
  "data": {
    "moment": "1990-08-13T01:00:00.000Z",
    "time_known": true,
    "time_basis": "clock",
    "zi_convention": "day_changes_at_23",
    "zi_hour": null,
    "solar_year": 1990,
    "pillars": {
      "year": {
        "name": "Geng Wu",
        "chinese": "庚午",
        "cycle_number": 7,
        "stem": {
          "id": "geng",
          "chinese": "庚",
          "element": "metal",
          "element_name": "Metal",
          "polarity": "yang",
          "ten_god": {
            "id": "bi_jian",
            "name": "Friend"
          }
        },
        "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": "Earth by the Roadside"
        }
      },
      "month": {
        "name": "Jia Shen",
        "chinese": "甲申",
        "cycle_number": 21,
        "stem": {
          "id": "jia",
          "chinese": "甲",
          "element": "wood",
          "element_name": "Wood",
          "polarity": "yang",
          "ten_god": {
            "id": "pian_cai",
            "name": "Indirect Wealth"
          }
        },
        "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": "Spring Water"
        }
      },
      "day": {
        "name": "Geng Xu",
        "chinese": "庚戌",
        "cycle_number": 47,
        "stem": {
          "id": "geng",
          "chinese": "庚",
          "element": "metal",
          "element_name": "Metal",
          "polarity": "yang"
        },
        "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"
            },
            {
              "id": "xin",
              "chinese": "辛",
              "element": "metal",
              "element_name": "Metal",
              "polarity": "yin"
            },
            {
              "id": "ding",
              "chinese": "丁",
              "element": "fire",
              "element_name": "Fire",
              "polarity": "yin"
            }
          ]
        },
        "nayin": {
          "chinese": "钗钏金",
          "name": "Hairpin Metal"
        }
      },
      "hour": {
        "name": "Ji Mao",
        "chinese": "己卯",
        "cycle_number": 16,
        "stem": {
          "id": "ji",
          "chinese": "己",
          "element": "earth",
          "element_name": "Earth",
          "polarity": "yin",
          "ten_god": {
            "id": "zheng_yin",
            "name": "Direct Resource"
          }
        },
        "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": "Earth on the City Wall"
        }
      }
    },
    "day_master": {
      "id": "geng",
      "chinese": "庚",
      "element": "metal",
      "element_name": "Metal",
      "polarity": "yang"
    },
    "elements": {
      "visible": {
        "wood": 2,
        "fire": 1,
        "earth": 2,
        "metal": 3,
        "water": 0
      },
      "hidden": {
        "wood": 1,
        "fire": 2,
        "earth": 3,
        "metal": 2,
        "water": 1
      }
    }
  },
  "meta": {
    "request_id": "req_example",
    "api_version": "v1",
    "engine_version": "2026.10.10",
    "mode": "live",
    "credits_charged": 2
  },
  "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
    }
  }
}

Bazi Four Pillars API

Request body

Response

Example request

Example response

More in Chinese