Chinese BaZi (Four Pillars) via API

Chinese BaZi, or the Four Pillars of Destiny, can be computed through the Vedika astrology API using the same birth details and the same API key you already use for Vedic, Western, and KP charts. You send a birth moment as datetime, latitude, longitude, and timezone; the response returns the four pillars (year, month, day, hour), their heavenly stems and earthly branches, the Day Master, the Ten Gods, the five-element balance, and the decade luck pillars. This guide walks through the request shapes, the astronomical edge cases that trip up naive implementations, and how to wire BaZi into an existing multi-system integration.

What the Four Pillars actually require

BaZi looks deceptively simple from the outside: four pairs of characters, eight glyphs, one chart. But each pillar is derived from a different astronomical or calendrical fact, and getting any one of them wrong silently corrupts the interpretation downstream.

• Year pillar is bounded by the start of spring (the solar term Li Chun), not by the lunar new year and not by January 1. A baby born in late January or early February can belong to the previous year's animal depending on the exact solar longitude at birth.
• Month pillar is bounded by the twelve major solar terms (the jie qi), which are fixed points of the Sun's apparent ecliptic longitude at 15-degree intervals. A calendar month is the wrong unit here.
• Day pillar follows an unbroken 60-day sexagenary cycle that has run continuously for millennia, independent of any month or year boundary.
• Hour pillar is keyed to the Chinese double-hour (a two-hour block) and to the day's heavenly stem, with the late-night block straddling midnight as a known complication.

Two of these four depend on the true position of the Sun, which is exactly why a real ephemeris matters rather than a lookup table of month names.

Why solar terms, not the Gregorian calendar

The solar terms are astronomical: the start of spring corresponds to the Sun reaching 315 degrees of tropical ecliptic longitude, and each subsequent term advances by 15 degrees. Because the Earth's orbit is slightly elliptical, the clock time at which the Sun crosses each boundary drifts year to year. An implementation that hard-codes "month pillar changes on the 5th" will be off by up to a day or two near the boundaries, which flips the month pillar's stem and branch and therefore the entire Ten Gods structure. Vedika computes the Sun's true longitude from the XALEN Ephemeris and assigns the pillar from the crossing, so the boundary is correct for any year and any location.

Computing a BaZi chart over the API

The natural-language entry point is POST /api/v1/astrology/query. You pass a question and a birthDetails object; Vedika selects the relevant system and returns a structured, sourced answer. For BaZi you simply ask in Four Pillars terms.

curl -X POST https://api.vedika.io/api/v1/astrology/query \
  -H "x-api-key: vk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Give me my BaZi Four Pillars, Day Master and Ten Gods",
    "birthDetails": {
      "datetime": "1990-02-03T06:45:00",
      "latitude": 31.2304,
      "longitude": 121.4737,
      "timezone": "Asia/Shanghai"
    }
  }'

Note the birth date in the example: 3 February 1990 sits right at the edge of the start of spring, so whether the year pillar reads as the Horse or the preceding Snake depends on the precise solar-term crossing. This is the canonical case to test any BaZi integration against.

Streaming the answer

For chat-style and voice surfaces, POST /api/v1/astrology/query/stream returns the same content as Server-Sent Events so you can render tokens as they arrive. The request body is identical; only the transport differs. Add "speed": "fast" to the body when you want the lower-latency path for interactive UIs.

Raw computation versus interpretation

If you run your own interpretive engine and only need the deterministic chart, the V2 computation surface under /v2/astrology/* accepts a flat birth payload (datetime, latitude, longitude, timezone) and returns structured data without a natural-language layer. This is the right choice when BaZi is one input into a larger product and you want the pillars, stems, branches, and luck cycles as JSON you can post-process.

// Generic fetch client — works with any HTTP runtime
async function getBaZi(birth) {
  const res = await fetch("https://api.vedika.io/api/v1/astrology/query", {
    method: "POST",
    headers: {
      "x-api-key": process.env.VEDIKA_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      question: "Four Pillars chart with Ten Gods and decade luck pillars",
      birthDetails: birth,
    }),
  });
  if (!res.ok) throw new Error(`Vedika ${res.status}`);
  return res.json();
}

const chart = await getBaZi({
  datetime: "1990-02-03T06:45:00",
  latitude: 31.2304,
  longitude: 121.4737,
  timezone: "Asia/Shanghai",
});

Reading the response: pillars, Day Master, Ten Gods

A Four Pillars result is organized around the Day Master, the heavenly stem of the day pillar, which represents the self. Every other stem and branch in the chart is then classified by its relationship to the Day Master into one of the Ten Gods (shi shen) categories.

The luck pillars deserve a note. The direction in which the da yun sequence runs (forward or backward through the sexagenary cycle) is set by the polarity of the year stem combined with the subject's sex, and the age at which the first luck pillar begins is computed from the distance in time to the adjacent solar term. Both of these are deterministic once the chart is correct, which is again why the solar-term boundaries have to be right.

Keeping interpretation honest

The astronomical layer and the interpretive layer are kept distinct on purpose. Pillar assignment and the five-element counts are pure computation. The interpretive meanings attached to the Ten Gods and element balances are treated as a sourced layer, traceable to the classical Four Pillars literature rather than invented on the fly. This separation means you can trust the chart math even where interpretive schools disagree, and it mirrors how Vedika handles citation discipline across every system it serves.

Where BaZi fits in a multi-system integration

The reason to compute BaZi through Vedika rather than bolting on a single-purpose Four Pillars library is consolidation. The same key, the same birth-details contract, and the same base URL cover Vedic sidereal, Western tropical, KP, plus Jaimini, Tajaka, Lal Kitab, numerology, and Chinese Four Pillars. For a product serving a pan-Asian audience, that means one integration instead of stitching together a Jyotish vendor and a separate BaZi vendor with two billing relationships and two failure modes.

import os, requests

def multi_system(birth, question):
    r = requests.post(
        "https://api.vedika.io/api/v1/astrology/query",
        headers={"x-api-key": os.environ["VEDIKA_API_KEY"]},
        json={"question": question, "birthDetails": birth},
        timeout=30,
    )
    r.raise_for_status()
    return r.json()

birth = {
    "datetime": "1990-02-03T06:45:00",
    "latitude": 31.2304,
    "longitude": 121.4737,
    "timezone": "Asia/Shanghai",
}

bazi = multi_system(birth, "Four Pillars and Ten Gods")
vedic = multi_system(birth, "Vedic birth chart and current dasha")
# Same key, same payload, two systems

Localization matters here too: Vedika serves responses in 30 languages including 14 Indic languages, so a Four Pillars reading can be returned in the language of the end user without a separate translation step.

Trying it without a key

You can explore request and response shapes against the free sandbox before provisioning a live key. When you are ready to wire it up, the developer docs cover authentication, error codes, and the full birth-details contract, and the pricing page lays out plans from Starter at twelve dollars a month through Enterprise, with per-query costs in the one-to-five-cent range. If you are coming from a single-purpose vendor such as Prokerala, AstrologyAPI.com, or RoxyAPI, the consolidation across systems is the practical difference rather than price alone.

Edge cases worth handling in client code

1. Solar-term boundary births. Any birth within roughly a day of a solar term needs the true Sun position, not a calendar approximation. Test your integration with a start-of-spring birth like the example above.
2. Unknown birth time. Without a time, the hour pillar cannot be assigned. Request a three-pillar chart; the response marks the hour pillar unavailable instead of fabricating one.
3. Timezone correctness. Always send an explicit IANA timezone. BaZi is sensitive to the local civil time of birth, and an inferred or dropped timezone will shift the hour pillar and, near midnight, the day pillar.
4. Late-night double-hour. The 11 PM to 1 AM block straddles the day boundary; how it is assigned affects both the hour and day pillars. The engine handles this consistently, but your display logic should expect a day-pillar shift for births in that window.

Key facts

• BaZi Four Pillars are available on the same Vedika API key as Vedic, Western, and KP, via POST /api/v1/astrology/query with standard birthDetails.
• Year and month pillars are derived from solar terms and the true Sun position, not the Gregorian calendar, so boundary births resolve correctly.
• The astronomical engine is the open-source XALEN Ephemeris (Apache-2.0), validated against JPL DE440 with no chart deviating beyond 0.1 degrees across a five-million-chart test; this is astronomical precision, separate from the sourced interpretive layer.
• Responses can include the Day Master, Ten Gods, five-element balance, and decade luck pillars; raw computation is available under /v2/astrology/*.
• One integration covers 700+ operations across 25 domains and 30 languages, so BaZi sits alongside Jyotish, Western, KP, Jaimini, and numerology without a second vendor.

FAQ

Common questions about computing Chinese Four Pillars through the API are answered below; the worked example above uses a start-of-spring birth precisely because it exercises the trickiest boundary.