CHINESE ASTROLOGY · JSON REST API

BaZi Four Pillars API

Build a Chinese Four Pillars view with inspectable time conventions. The response keeps stems, branches, hidden stems and symbolic relationships as structured facts rather than hiding them in a prose-only reading.

AvailablePOST /v1/chinese/bazi

50,000 credits per monthly allowance · no trial · no automatic overage charges. Plan details ↗

BUILD AROUND THE DATA

What this API provides.

Get Four Pillars, hidden stems, ten gods, visible element counts and pillar relations with explicit civil-time and Beijing solar-term conventions.

01

Year, month, day and known-time hour pillars

02

Stem/branch elements, polarity, animal and hidden stems

03

Ten-god labels relative to the day master

04

Visible element counts and selected stem/branch relations

Send

  • birth.date and IANA timezone
  • Local time when known; an unknown time omits the hour pillar
  • Locale; no longitude-based true-solar correction is applied

Receive

  • pillars with stems, branches and hidden-stem detail
  • five_elements.counts and selected pillar relations
  • A declared day-boundary/solar-term method and fact-linked prose
ACTUAL PILLAR DATA

Four pillars, visible facts.

This view is drawn directly from the sample JSON. It is not a weighted strength assessment.

year庚午

metal / fire · horse

month辛巳

metal / fire · snake

day丙戌

fire / earth · dog

hour乙未

wood / earth · goat

INSPECT BEFORE SUBSCRIBING

Real input. Real output.

Precomputed by the actual calculation engine and response formatter, using synthetic example data. No purchased access or paid provider call was needed.

Request JSON POST /v1/chinese/bazi
{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  }
}
Response JSON · selected fields
{
  "request_id": "8391c2e0597c12c18e10a847981e38a2",
  "api_version": "v1",
  "locale": "en",
  "data": {
    "pillars": {
      "year": {
        "gan_zhi": "庚午",
        "stem": "庚",
        "branch": "午",
        "stem_element": "metal"
      },
      "month": {
        "gan_zhi": "辛巳",
        "stem": "辛",
        "branch": "巳",
        "stem_element": "metal"
      },
      "day": {
        "gan_zhi": "丙戌",
        "stem": "丙",
        "branch": "戌",
        "stem_element": "fire"
      },
      "hour": {
        "gan_zhi": "乙未",
        "stem": "乙",
        "branch": "未",
        "stem_element": "wood"
      }
    },
    "day_master": {
      "stem": "丙",
      "element": "fire"
    },
    "five_elements": {
      "counts": {
        "wood": 1,
        "fire": 3,
        "earth": 2,
        "metal": 2
      },
      "basis": "visible stems and branch primary elements; unweighted, excludes hidden stems",
      "complete": true
    },
    "relations": [
      {
        "type": "six_combination",
        "pillars": [
          "year"
        ],
        "branches": [
          "午"
        ]
      },
      {
        "type": "stem_combination",
        "pillars": [
          "year"
        ],
        "stems": [
          "庚"
        ]
      }
    ],
    "method": {
      "library": "lunar-python",
      "library_version": "1.4.8",
      "sect": 2,
      "day_boundary": "local civil midnight",
      "year_boundary": "Li Chun exact instant",
      "month_boundary": "Jie exact instant",
      "term_reference_timezone": "UTC+08:00 converted to birth instant"
    }
  },
  "interpretation": {
    "locale": "en",
    "kind": "chinese/bazi",
    "disclaimer": "Symbolic reflection, not a verified prediction or professional advice.",
    "coverage": {
      "total_facts": 8,
      "selected_facts": 8,
      "omitted_count": 0,
      "selection_method": "all-source-facts-v1",
      "full_numeric_data_unchanged": true
    },
    "method": {
      "engine": "celestack-original-rules-v1",
      "corpus": "celestack-original-compositional-v1",
      "corpus_version": "2026-11-17.2",
      "fallback_locale": null,
      "editorial_status": "agent-authored; independent linguistic review pending",
      "predictive_validity": "symbolic interpretations are not scientifically validated predictions",
      "chinese_solar_terms": "numeric calendar output only; no rule paragraphs in this corpus"
    },
    "items": [
      {
        "fact_id": "chinese.pillar.year",
        "title": "Year pillar",
        "text": "Year pillar: 庚午. Stem element: Metal; branch element: Fire; polarity: Yang. Symbolic reflection: structure and boundaries. These calendar symbols do not establish personal traits or future events.",
        "source": {
          "id": "chinese.pillar.year",
          "type": "chinese_pillar",
          "position": "year",
          "gan_zhi": "庚午",
          "stem": "庚",
          "branch": "午",
          "stem_element": "metal",
          "branch_element": "fire",
          "polarity": "yang",
          "animal": "horse",
          "ten_god": "indirect_wealth",
          "hidden_stems": [
            {
              "stem": "丁",
              "element": "fire",
              "ten_god": "rob_wealth"
            },
            {
              "stem": "己",
              "element": "earth",
              "ten_god": "hurting_officer"
            }
          ]
        }
      }
    ]
  },
  "warnings": [],
  "credits_used": 5
}

The response preview selects whole fields and array entries for readability; no numeric values have been replaced. The full download preserves all fields, arrays and interpretation. The request_id is synthetic, and credits_used shows the configured successful-request cost; no credits were consumed.

cURL request — use your own API key and a new idempotency key
curl --request POST 'https://api.celestackapi.com/v1/chinese/bazi' \
+  --header 'Authorization: Bearer YOUR_API_KEY' \
+  --header 'Content-Type: application/json' \
+  --header 'Idempotency-Key: bazi-api-example-001' \
+  --data '{
  "locale": "en",
  "birth": {
    "date": "1990-05-21",
    "time": "14:30:00",
    "timezone": "Europe/Madrid",
    "latitude": 40.4168,
    "longitude": -3.7038
  }
}'

Example computed 2026-11-17. Full fixture manifest, engine versions and SHA-256 checksums ↗

YOUR PRODUCT, YOUR EXPERIENCE

Ways to use it.

  • Four Pillars onboarding and chart displays
  • A visible-element visualization with explicit counting rules
  • Localized symbolic readings backed by pillar facts

12 response locales

English, Ukrainian, Japanese, Spanish, French, German, Portuguese, Arabic, Italian, Hindi, Chinese and Korean.

Calculation values remain language-independent. Localized rule text is agent-authored; independent native-language review remains pending. Machine-readable field names stay stable.

KNOW THE CONVENTIONS

Limits and interpretation.

  • Year/month pillars use the real instant against Beijing solar-term boundaries; day/hour pillars use local civil time.
  • There is no longitude or true-solar-time correction. Visible element counts are not a full weighted strength or useful-god analysis.
  • Luck pillars, annual fortune predictions and remedies are not included. Unknown-time boundary uncertainty is explicit.

Interpretive content is for symbolic reflection and entertainment. It is not a verified personal prediction or professional advice. Read the API conventions ↗

PREDICTABLE ACCESS

Choose your billing.

Both options include 50,000 credits per monthly allowance, resetting monthly. No trial and no automatic overage. Custom needs use a contact form.

5,000credits per UTC day
60requests per minute
5,000new operation attempts per UTC day
32 MiBmaximum stored JSON result

Saved results: 7-day retention, up to 128 MiB per organization on this initial shared deployment, with a 512 MiB shared retained-result limit. Capacity can return a temporary error; there are no automatic extra charges. Production artifacts have separate retention. All usage and resource limits ↗. Checkout availability is shown in your account.

DEVELOPER QUESTIONS

Frequently asked questions.

Does the endpoint use true solar time?

No. The declared profile uses local civil time for day/hour pillars, with year/month solar-term boundaries evaluated at the real instant in Beijing time.

Are element counts a strength assessment?

No. They count the visible stem and branch elements. They are not a weighted hidden-stem, seasonal-strength or useful-god assessment.

Can I omit the birth time?

Yes. The hour pillar is omitted. If a solar-term boundary makes the year or month pillar uncertain within that local day, the relevant pillar is also marked uncertain.

What does access cost?

Access is USD 39.99 per month or USD 199 billed annually, with no trial. Both billing options provide 50,000 credits per monthly allowance. 5 credits per successful request or job. Daily credit, attempt, rate and resource limits apply. There are no automatic overage charges.

CONNECT THE BUILDING BLOCKS

Related APIs.

View every API