Chinese Calendar Date API

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

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

Chinese Calendar Date API

Request body

Response

Example request

Example response

More in Chinese