True solar time API

True solar time is the hour angle of the apparent Sun at the birth longitude, carried round by half a day, taken from the Swiss Ephemeris apparent right ascension against Greenwich mean sidereal time. It decomposes into two terms that are reported separately. The meridian term is the birthplace's distance from its zone meridian, four minutes per degree, and it is the large one: China runs one offset from Kashgar to Harbin, so a Xinjiang birth sits nearly three hours from its own clock. The equation of time is the Sun's own annual wobble, up to about sixteen minutes either way, and it is the term almanac tables usually omit. The response also reports whether the correction crossed midnight, since that moves the day pillar and not only the hour.

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

{
  "ok": true,
  "data": {
    "clockTime": "14:30:00",
    "trueSolarTime": "12:24:06",
    "totalCorrectionMinutes": -125.89,
    "longitudeCorrectionMinutes": -129.6,
    "equationOfTimeMinutes": 3.71,
    "dayShift": 0,
    "date": "1990-05-15"
  }
}

Use it whenever a chart depends on the double-hour and the birthplace is far from its zone meridian: BaZi hour pillars, Zi Wei hour palaces, any Chinese reading for a birth in western China, in a wide zone such as Spain or Argentina, or anywhere a colonial-era zone boundary sits well off the meridian. It also stands alone as a utility for sundial work and for anybody reconciling a printed almanac against a clock time. Inside our own BaZi surface the same correction is available as a trueSolarTime flag, so you rarely need to call this endpoint and then re-send the result.

The correction reaches the day and the hour and deliberately does not reach the year and the month. Li Chun and the 節 are world instants, and a sundial reading has nothing to say about when the Sun crosses 315 degrees. Applying the correction to the year boundary is a real and common bug: it gives a birth seventeen minutes after Li Chun the previous year and four wrong pillars. The equation of time is pinned to the four published turning points of the annual curve and its four zeros.