Chinese metaphysics: questions we get

Why does your calculator give different pillars from another one?

Almost always for one of four reasons, and none of them is a bug. They are school choices, and most calculators make them silently. Our answers, and a run against an external dataset, live on the conventions page.

Axis	Our answer
Year boundary	立春 Lichun, the exact instant from the ephemeris
Day rollover	23:00, so the early 子時 belongs to the next day
True solar time	off by default, switched on by a flag
Daylight saving	settled by the timezoneOffset you send

Does the year start at Chinese New Year or at Lichun?

At Lichun, and the two dates are two or three weeks apart every year. Chinese New Year opens the lunar year and the festival; the pillars are built on the solar year, which Lichun opens. Somebody born on 10 February 2026 is already a Horse by pillars, even though New Year fell on 17 February.

/v1/chinese/lunar-date returns chineseNewYear as its own field precisely because it is a different quantity, not a synonym.

What do I send when the birth time is unknown?

Do not send time at all. Three pillars out of four are computed and the hour pillar simply does not appear. That is more honest than substituting noon: an invented time produces an hour pillar that looks like a fact and is not one, and it drags along every 神煞 that depends on it.

What changes without the hour:

• the hour pillar is absent
• the secret animal is absent
• the element balance counts six characters instead of eight
• day-master strength shifts, because a quarter of the chart is gone

When should I switch on trueSolarTime?

When the birth place sits far from its time zone’s meridian. China runs on one UTC+8 from Kashgar to Harbin, and in Xinjiang the discrepancy reaches three hours, which is a full double-hour and a half. The flag moves the day and the hour, and deliberately does not move the year and the month: Lichun is a world instant, and a sundial reading has nothing to say about it.

curl -X POST https://api.astroway.info/v1/chinese/true-solar-time \
  -H "X-Api-Key: $ASTROWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"1990-05-15","time":"14:30:00","timezoneOffset":8,"longitude":87.6}'

Why are your 藏干 in a different order from my book?

Our list is ordered by the 人元司令 day count, that is by the order in which the hidden stems govern the month. The role (principal, middle, residual) is a separate field and does not depend on the position. On the four storage branches 丑辰未戌 the middle role belongs to the element the branch stores, not to the second item in the list. This is the point where public implementations disagree most often.

Do you compute Zi Wei Dou Shu?

Yes. POST /v1/ziwei/chart builds the whole chart: the soul and body palaces from the lunar month and the double-hour, the five-element class from the soul palace pillar, 紫微 by the borrow-and-divide rule, the other thirteen main stars, six lucky and six malefic, thirty-one minor stars, the twelve life stages, the 博士, 將前 and 歲前 cycles, the decade limits and the annual one, with the 四化 marked on the stars themselves.

Eleven /ziwei/* routes stay reference tables of the palaces and the stars. They carry a computed: false field, cost half the standard rate and return the same thing for any date: it is a glossary, and it says so. /ziwei/full-chart is deprecated until 2027-11-26 in favour of /ziwei/chart.

Details and how it was verified: Zi Wei Dou Shu.

What do you offer over a free library?

Nothing, if all you need is the pillars. lunar-typescript is MIT, computes them in your own process, offline, with no rate limit, and we do not suggest paying for something you can decline to buy.

The difference starts after that: 神煞, branch interactions 刑冲合害, day-master strength, true solar time, flying stars by sitting and facing, the Kua number, Tong Shu date selection. And 21 languages over all of it. Plus the thing people actually pay for: one convention for a team whose site is PHP, whose app is JavaScript and whose crons are Python.

Why are animal names translated but stems left in pinyin?

Animals and elements have settled names in every language, so they are translated: 午 is Caballo in Spanish and ウマ in Japanese. Stems, branches, 納音 and star names have no settled names, and their international form is pinyin next to the character. Inventing a Czech word for 甲 would be worse than leaving 甲. The same rule governs the Human Design block.

What date range do you accept?

Years 2 through 2899. The calendar is derived from the ephemeris, so it works well past the printed tables, but not without limit: outside the domain you get a 400 that names the field, not a 500.

{ "ok": false, "error": { "code": "INVALID_INPUT",
  "message": "Validation failed: year: Too big: expected number to be <=2899" } }