Back to Docs

BaZi Time Correction

BaZi Time Correction API

POST/api/v1/chinese/bazi/time-correction

Convert civil clock time into Local Mean Time and true solar time for BaZi workflows. Use it when your app needs to show the correction math, audit an hour-pillar shift, or explain why time_standard changes the result.

Authentication

This endpoint is authenticated. Include x-api-key: YOUR_API_KEY with every production request. It uses the same account key and rate-limit system as the other Chinese astrology endpoints.

Full URL

https://api.freeastroapi.com/api/v1/chinese/bazi/time-correction

Request Parameters

Field
year
Type
integer
Required
Yes
Description
Local civil year for the date/time being corrected.
Field
month
Type
integer
Required
Yes
Description
Local civil month, from 1 to 12.
Field
day
Type
integer
Required
Yes
Description
Local civil day of month.
Field
hour
Type
integer
Required
No
Description
Local civil hour in 24-hour time. Defaults to 12.
Field
minute
Type
integer
Required
No
Description
Local civil minute. Defaults to 0.
Field
lat
Type
float
Required
No
Description
Latitude in decimal degrees. Provide both lat and lng, or provide a city that can be resolved.
Field
lng
Type
float
Required
No
Description
Longitude in decimal degrees. Used to calculate local mean time and longitude correction.
Field
city
Type
string
Required
No
Description
Optional city name for coordinate lookup when lat/lng are not supplied.
Field
tz_str
Type
string
Required
No
Description
IANA timezone such as Europe/Paris, or AUTO to resolve from the supplied location. Defaults to AUTO.

Example Request

curl -X POST "https://api.freeastroapi.com/api/v1/chinese/bazi/time-correction" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "year": 2025,
    "month": 12,
    "day": 30,
    "hour": 12,
    "minute": 0,
    "lat": 48.8566,
    "lng": 2.3522,
    "tz_str": "Europe/Paris"
  }'

Response Fields

Field
civil_time
Type
datetime
Required
n/a
Description
The input wall-clock time assembled from year, month, day, hour, and minute.
Field
lmt
Type
datetime
Required
n/a
Description
Local Mean Time derived from longitude and the resolved timezone handling.
Field
true_solar_relative
Type
datetime
Required
n/a
Description
Clock time plus longitude correction relative to the timezone meridian, plus Equation of Time.
Field
true_solar_absolute
Type
datetime
Required
n/a
Description
Absolute sundial-style solar time based on LMT plus Equation of Time.
Field
equation_of_time_minutes
Type
float
Required
n/a
Description
Equation of Time offset in minutes for the requested date.
Field
longitude_correction_minutes
Type
float
Required
n/a
Description
Minutes added or subtracted because the longitude differs from the timezone standard meridian.
Field
standard_meridian
Type
float
Required
n/a
Description
Timezone standard meridian in degrees, calculated from the standard UTC offset.
Field
resolved_timezone
Type
string
Required
n/a
Description
Timezone used for the correction after AUTO or explicit timezone handling.
Field
dst_offset_hours
Type
float
Required
n/a
Description
Daylight-saving offset detected for the requested date, in hours.
Field
modalities
Type
object
Required
n/a
Description
Human-readable explanations for civil, true_solar, and true_solar_absolute time modes.

Sample Response

{
  "civil_time": "2025-12-30T12:00:00",
  "lmt": "2025-12-30T11:09:24.528000",
  "true_solar_relative": "2025-12-30T11:06:48.691710",
  "true_solar_absolute": "2025-12-30T11:06:48.691710",
  "equation_of_time_minutes": -2.6,
  "longitude_correction_minutes": -50.59,
  "standard_meridian": 15.0,
  "resolved_timezone": "Europe/Paris",
  "dst_offset_hours": 0.0,
  "modalities": {
    "civil": "Wall clock time. Standardized, but ignores local solar reality.",
    "true_solar": "Relative Solar Time. Corrects for position within your timezone. Preserves the 'feel' of the hour.",
    "true_solar_absolute": "Absolute Sundial. Pure solar time based on longitude and Earth's orbit. Ignores timezones entirely."
  }
}

When to Use This Endpoint

Use this endpoint when you need a transparent breakdown of the conversion from civil time totrue_solar or true_solar_absolute.

If your app only needs the final Four Pillars chart, callBaZi chartdirectly and set time_standard in that request.

FAQ

Does the BaZi time correction endpoint require an API key?

Yes. Production requests must include x-api-key with your FreeAstroAPI key. The website calculator is not a substitute for application authentication.

Should I call time-correction before every BaZi chart request?

No. If you only need a BaZi chart, call /api/v1/chinese/bazi directly and set time_standard to true_solar or true_solar_absolute. Use this endpoint when you need to display or audit the time conversion itself.

Can I use a city instead of coordinates?

Yes, but direct lat/lng values are more deterministic for production apps. If you provide city, the API attempts coordinate lookup before calculating the correction.

Related Endpoints

BaZi Chart

Calculate the Four Pillars with time_standard options.

Timezone System

Understand timezone, coordinate, and LMT behavior.