Chinese

The four pillars of Bazi, luck pillars, a year against a chart, relations between two charts, the birth animal by both conventions, the Chinese calendar date and the 24 solar terms.

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

POST/v1/chinese/bazi

2 credits · Secret key (test or live) · getBazi · Page for this operation

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
    }
  }
}

The ten-year luck pillars, their direction and the age they start

POST/v1/chinese/luck-pillars

1 credit · Secret key (test or live) · getLuckPillars · Page for this operation

The traditional rule uses gender and the polarity of the year stem to set the direction. Three days from birth to the jie count as one year of age. A birth time is required.

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.
gender string required
The traditional rule needs it. Used for this response and not stored.
one of male, female
count integer
≥ 1 · ≤ 12 · default 8
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:

direction string required
one of forward, backward
days_to_jie number required
start_age number required
rule string required
pillars array of object required
- order integer required
- from_age number required
- from_year integer 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/luck-pillars' \
  -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}},"gender":"female","count":4}'

Node.js

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

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

Example response

200 OK · 7,594 characters

{
  "data": {
    "direction": "backward",
    "days_to_jie": 5.26,
    "start_age": 1.75,
    "rule": "3 days from birth to the jie count as 1 year of age.",
    "pillars": [
      {
        "order": 1,
        "from_age": 1.75,
        "from_year": 1992,
        "pillar": {
          "name": "Gui Wei",
          "chinese": "癸未",
          "cycle_number": 20,
          "stem": {
            "id": "gui",
            "chinese": "癸",
            "element": "water",
            "element_name": "Water",
            "polarity": "yin",
            "ten_god": {
              "id": "shang_guan",
              "name": "Hurting Officer"
            }
          },
          "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": "Willow Wood"
          }
        }
      },
      {
        "order": 2,
        "from_age": 11.75,
        "from_year": 2002,
        "pillar": {
          "name": "Ren Wu",
          "chinese": "壬午",
          "cycle_number": 19,
          "stem": {
            "id": "ren",
            "chinese": "壬",
            "element": "water",
            "element_name": "Water",
            "polarity": "yang",
            "ten_god": {
              "id": "shi_shen",
              "name": "Eating God"
            }
          },
          "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": "Willow Wood"
          }
        }
      },
      {
        "order": 3,
        "from_age": 21.75,
        "from_year": 2012,
        "pillar": {
          "name": "Xin Si",
          "chinese": "辛巳",
          "cycle_number": 18,
          "stem": {
            "id": "xin",
            "chinese": "辛",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yin",
            "ten_god": {
              "id": "jie_cai",
              "name": "Rob Wealth"
            }
          },
          "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": "White Wax Metal"
          }
        }
      },
      {
        "order": 4,
        "from_age": 31.75,
        "from_year": 2022,
        "pillar": {
          "name": "Geng Chen",
          "chinese": "庚辰",
          "cycle_number": 17,
          "stem": {
            "id": "geng",
            "chinese": "庚",
            "element": "metal",
            "element_name": "Metal",
            "polarity": "yang",
            "ten_god": {
              "id": "bi_jian",
              "name": "Friend"
            }
          },
          "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": "White Wax Metal"
          }
        }
      }
    ]
  },
  "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
    }
  },
  "gender": "female",
  "count": 4
}

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 · Page for this operation

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
}

Harmonies and conflicts between two charts' year and day pillars

POST/v1/chinese/compatibility

1 credit · Secret key (test or live) · getChineseCompatibility · Page for this operation

It lists the relations and counts them. It gives no percentage, because the classical rules do not.

Request body

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

animals object required
- a string required
- b string required
- a_name string required
- b_name string required
year_branches array of object required
- id string required
- kind string
  one of harmony, conflict
- element string
day_branches array of object required
- id string required
- kind string
  one of harmony, conflict
- element string
day_stems object or null required
One of:
1. object
  Fields
  - id string required
  - kind string
    one of harmony, conflict
  - element string
2. null
harmonies integer required
conflicts integer required
basis string required
one of convention

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

Example request

curl -X POST 'https://api.astrologics.in/v1/chinese/compatibility' \
  -H 'Authorization: Bearer al_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"person_a":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}},"person_b":{"date":"1992-03-02","time":"14:10","place":{"latitude":19.076,"longitude":72.8777}}}'

Node.js

const res = await fetch("https://api.astrologics.in/v1/chinese/compatibility", {
  method: "POST",
  headers: { Authorization: "Bearer al_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "person_a": {
      "date": "1990-08-13",
      "time": "06:30",
      "place": {
        "latitude": 28.6139,
        "longitude": 77.209
      }
    },
    "person_b": {
      "date": "1992-03-02",
      "time": "14:10",
      "place": {
        "latitude": 19.076,
        "longitude": 72.8777
      }
    }
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));

Python

import json
import urllib.error
import urllib.request

body = {
    "person_a": {
        "date": "1990-08-13",
        "time": "06:30",
        "place": {
            "latitude": 28.6139,
            "longitude": 77.209,
        },
    },
    "person_b": {
        "date": "1992-03-02",
        "time": "14:10",
        "place": {
            "latitude": 19.076,
            "longitude": 72.8777,
        },
    },
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/chinese/compatibility",
    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/compatibility');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer al_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"person_a":{"date":"1990-08-13","time":"06:30","place":{"latitude":28.6139,"longitude":77.209}},"person_b":{"date":"1992-03-02","time":"14:10","place":{"latitude":19.076,"longitude":72.8777}}}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;

Example response

200 OK · 522 characters

{
  "data": {
    "animals": {
      "a": "horse",
      "b": "monkey",
      "a_name": "Horse",
      "b_name": "Monkey"
    },
    "year_branches": [],
    "day_branches": [
      {
        "id": "punishment",
        "kind": "conflict"
      }
    ],
    "day_stems": null,
    "harmonies": 0,
    "conflicts": 1,
    "basis": "convention"
  },
  "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)

{
  "person_a": {
    "date": "1990-08-13",
    "time": "06:30",
    "place": {
      "latitude": 28.6139,
      "longitude": 77.209
    }
  },
  "person_b": {
    "date": "1992-03-02",
    "time": "14:10",
    "place": {
      "latitude": 19.076,
      "longitude": 72.8777
    }
  }
}

The birth year animal by Li Chun and by Lunar New Year, and whether they agree

POST/v1/chinese/zodiac

1 credit · Secret key (test or live) · getChineseZodiac · Page for this operation

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

by_li_chun object required
- year integer required
- animal string required
- animal_name string required
- stem_element string required
- stem_element_name string required
- polarity string required
- pillar string required
- began string (date-time) required
by_lunar_new_year object required
- year integer required
- animal string required
- animal_name string required
- stem_element string required
- stem_element_name string required
- polarity string required
- pillar string required
- began string (date) required
  e.g. "1990-08-13"
agree boolean required
time_known boolean required

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

Example request

curl -X POST 'https://api.astrologics.in/v1/chinese/zodiac' \
  -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/zodiac", {
  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/zodiac",
    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/zodiac');
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 · 746 characters

{
  "data": {
    "by_li_chun": {
      "year": 1990,
      "animal": "horse",
      "animal_name": "Horse",
      "stem_element": "metal",
      "stem_element_name": "Metal",
      "polarity": "yang",
      "pillar": "庚午",
      "began": "1990-02-04T02:13:58.005Z"
    },
    "by_lunar_new_year": {
      "year": 1990,
      "animal": "horse",
      "animal_name": "Horse",
      "stem_element": "metal",
      "stem_element_name": "Metal",
      "polarity": "yang",
      "pillar": "庚午",
      "began": "1990-01-27"
    },
    "agree": true,
    "time_known": true
  },
  "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
    }
  }
}

A Gregorian date in the Chinese calendar: lunar month and day, leap month, day pillar and solar term

POST/v1/chinese/date

1 credit · Secret key (test or live) · getChineseDate · Page for this operation

Request body

date string (date) required
e.g. "1990-08-13"
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:

date string (date) required
e.g. "1990-08-13"
lunar object required
- year integer required
- month integer required
  ≥ 1 · ≤ 12
- leap_month boolean required
- day integer required
  ≥ 1 · ≤ 30
- month_days integer required
- year_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
- animal string required
- animal_name string required
day_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
current_term object required
- id string required
- chinese string required
next_term object required
- id string required
- chinese string required
- at string (date-time) required
time_zone string required

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

Example request

curl -X POST 'https://api.astrologics.in/v1/chinese/date' \
  -H 'Authorization: Bearer al_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"date":"2026-11-02"}'

Node.js

const res = await fetch("https://api.astrologics.in/v1/chinese/date", {
  method: "POST",
  headers: { Authorization: "Bearer al_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "date": "2026-11-02"
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));

Python

import json
import urllib.error
import urllib.request

body = {
    "date": "2026-11-02",
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/chinese/date",
    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/date');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer al_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"date":"2026-11-02"}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;

Example response

200 OK · 2,791 characters

{
  "data": {
    "date": "2026-11-02",
    "lunar": {
      "year": 2026,
      "month": 9,
      "leap_month": false,
      "day": 24,
      "month_days": 30,
      "year_pillar": {
        "name": "Bing Wu",
        "chinese": "丙午",
        "cycle_number": 43,
        "stem": {
          "id": "bing",
          "chinese": "丙",
          "element": "fire",
          "element_name": "Fire",
          "polarity": "yang"
        },
        "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"
            },
            {
              "id": "ji",
              "chinese": "己",
              "element": "earth",
              "element_name": "Earth",
              "polarity": "yin"
            }
          ]
        },
        "nayin": {
          "chinese": "天河水",
          "name": "Water of the Heavenly River"
        }
      },
      "animal": "horse",
      "animal_name": "Horse"
    },
    "day_pillar": {
      "name": "Geng Chen",
      "chinese": "庚辰",
      "cycle_number": 17,
      "stem": {
        "id": "geng",
        "chinese": "庚",
        "element": "metal",
        "element_name": "Metal",
        "polarity": "yang"
      },
      "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"
          },
          {
            "id": "yi",
            "chinese": "乙",
            "element": "wood",
            "element_name": "Wood",
            "polarity": "yin"
          },
          {
            "id": "gui",
            "chinese": "癸",
            "element": "water",
            "element_name": "Water",
            "polarity": "yin"
          }
        ]
      },
      "nayin": {
        "chinese": "白蜡金",
        "name": "White Wax Metal"
      }
    },
    "current_term": {
      "id": "shuang_jiang",
      "chinese": "霜降"
    },
    "next_term": {
      "id": "li_dong",
      "chinese": "立冬",
      "at": "2026-11-07T09:52:33.362Z"
    },
    "time_zone": "UTC+8"
  },
  "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)

{
  "date": "2026-11-02"
}

The 24 solar terms of a year, to the minute

POST/v1/chinese/solar-terms

1 credit · Secret key (test or live) · getSolarTerms · Page for this operation

Request body

year integer required
≥ 1901 · ≤ 2099

No other fields are accepted.

Response

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

year integer required
count integer required
terms array of object required
- id string required
- chinese string required
- sun_longitude number required
- kind string required
  one of jie, zhongqi
- at string (date-time) required
- beijing string required
  The same moment in UTC+8.

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

Example request

curl -X POST 'https://api.astrologics.in/v1/chinese/solar-terms' \
  -H 'Authorization: Bearer al_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"year":2026}'

Node.js

const res = await fetch("https://api.astrologics.in/v1/chinese/solar-terms", {
  method: "POST",
  headers: { Authorization: "Bearer al_test_YOUR_KEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    "year": 2026
  }),
});
console.log(JSON.stringify(await res.json(), null, 2));

Python

import json
import urllib.error
import urllib.request

body = {
    "year": 2026,
}

req = urllib.request.Request(
    "https://api.astrologics.in/v1/chinese/solar-terms",
    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/solar-terms');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_HTTPHEADER => ['Authorization: Bearer al_test_YOUR_KEY', 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS => '{"year":2026}',
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch), PHP_EOL;

Example response

200 OK · 5,096 characters

{
  "data": {
    "year": 2026,
    "count": 24,
    "terms": [
      {
        "id": "xiao_han",
        "chinese": "小寒",
        "sun_longitude": 285,
        "kind": "jie",
        "at": "2026-01-05T08:23:03.114Z",
        "beijing": "2026-01-05 16:23"
      },
      {
        "id": "da_han",
        "chinese": "大寒",
        "sun_longitude": 300,
        "kind": "zhongqi",
        "at": "2026-01-20T01:44:42.360Z",
        "beijing": "2026-01-20 09:44"
      },
      {
        "id": "li_chun",
        "chinese": "立春",
        "sun_longitude": 315,
        "kind": "jie",
        "at": "2026-02-03T20:01:54.541Z",
        "beijing": "2026-02-04 04:01"
      },
      {
        "id": "yu_shui",
        "chinese": "雨水",
        "sun_longitude": 330,
        "kind": "zhongqi",
        "at": "2026-02-18T15:51:32.389Z",
        "beijing": "2026-02-18 23:51"
      },
      {
        "id": "jing_zhe",
        "chinese": "惊蛰",
        "sun_longitude": 345,
        "kind": "jie",
        "at": "2026-03-05T13:58:43.971Z",
        "beijing": "2026-03-05 21:58"
      },
      {
        "id": "chun_fen",
        "chinese": "春分",
        "sun_longitude": 0,
        "kind": "zhongqi",
        "at": "2026-03-20T14:45:36.044Z",
        "beijing": "2026-03-20 22:45"
      },
      {
        "id": "qing_ming",
        "chinese": "清明",
        "sun_longitude": 15,
        "kind": "jie",
        "at": "2026-04-04T18:39:59.161Z",
        "beijing": "2026-04-05 02:39"
      },
      {
        "id": "gu_yu",
        "chinese": "谷雨",
        "sun_longitude": 30,
        "kind": "zhongqi",
        "at": "2026-04-20T01:39:09.897Z",
        "beijing": "2026-04-20 09:39"
      },
      {
        "id": "li_xia",
        "chinese": "立夏",
        "sun_longitude": 45,
        "kind": "jie",
        "at": "2026-05-05T11:49:09.475Z",
        "beijing": "2026-05-05 19:49"
      },
      {
        "id": "xiao_man",
        "chinese": "小满",
        "sun_longitude": 60,
        "kind": "zhongqi",
        "at": "2026-05-21T00:37:16.958Z",
        "beijing": "2026-05-21 08:37"
      },
      {
        "id": "mang_zhong",
        "chinese": "芒种",
        "sun_longitude": 75,
        "kind": "jie",
        "at": "2026-06-05T15:48:59.457Z",
        "beijing": "2026-06-05 23:48"
      },
      {
        "id": "xia_zhi",
        "chinese": "夏至",
        "sun_longitude": 90,
        "kind": "zhongqi",
        "at": "2026-06-21T08:25:00.316Z",
        "beijing": "2026-06-21 16:25"
      },
      {
        "id": "xiao_shu",
        "chinese": "小暑",
        "sun_longitude": 105,
        "kind": "jie",
        "at": "2026-07-07T01:57:22.386Z",
        "beijing": "2026-07-07 09:57"
      },
      {
        "id": "da_shu",
        "chinese": "大暑",
        "sun_longitude": 120,
        "kind": "zhongqi",
        "at": "2026-07-22T19:13:18.217Z",
        "beijing": "2026-07-23 03:13"
      },
      {
        "id": "li_qiu",
        "chinese": "立秋",
        "sun_longitude": 135,
        "kind": "jie",
        "at": "2026-08-07T11:42:56.663Z",
        "beijing": "2026-08-07 19:42"
      },
      {
        "id": "chu_shu",
        "chinese": "处暑",
        "sun_longitude": 150,
        "kind": "zhongqi",
        "at": "2026-08-23T02:18:58.412Z",
        "beijing": "2026-08-23 10:18"
      },
      {
        "id": "bai_lu",
        "chinese": "白露",
        "sun_longitude": 165,
        "kind": "jie",
        "at": "2026-09-07T14:41:44.296Z",
        "beijing": "2026-09-07 22:41"
      },
      {
        "id": "qiu_fen",
        "chinese": "秋分",
        "sun_longitude": 180,
        "kind": "zhongqi",
        "at": "2026-09-23T00:05:38.617Z",
        "beijing": "2026-09-23 08:05"
      },
      {
        "id": "han_lu",
        "chinese": "寒露",
        "sun_longitude": 195,
        "kind": "jie",
        "at": "2026-10-08T06:29:58.055Z",
        "beijing": "2026-10-08 14:29"
      },
      {
        "id": "shuang_jiang",
        "chinese": "霜降",
        "sun_longitude": 210,
        "kind": "zhongqi",
        "at": "2026-10-23T09:38:24.266Z",
        "beijing": "2026-10-23 17:38"
      },
      {
        "id": "li_dong",
        "chinese": "立冬",
        "sun_longitude": 225,
        "kind": "jie",
        "at": "2026-11-07T09:52:33.362Z",
        "beijing": "2026-11-07 17:52"
      },
      {
        "id": "xiao_xue",
        "chinese": "小雪",
        "sun_longitude": 240,
        "kind": "zhongqi",
        "at": "2026-11-22T07:23:34.115Z",
        "beijing": "2026-11-22 15:23"
      },
      {
        "id": "da_xue",
        "chinese": "大雪",
        "sun_longitude": 255,
        "kind": "jie",
        "at": "2026-12-07T02:52:47.191Z",
        "beijing": "2026-12-07 10:52"
      },
      {
        "id": "dong_zhi",
        "chinese": "冬至",
        "sun_longitude": 270,
        "kind": "zhongqi",
        "at": "2026-12-21T20:50:22.187Z",
        "beijing": "2026-12-22 04:50"
      }
    ]
  },
  "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)

{
  "year": 2026
}