Back to Docs

Timezone System

Timezone System & LMT

Our API features a robust, historically accurate time-resolution engine. It automatically handles the complexities of changing timezones, Daylight Savings Time (DST), and the historical shift from Local Mean Time (LMT) to Standard Time.

Comparison Guide: For a conceptual deep-dive into why this matters (with examples), see our Timezones & LMT Guide.

The tz_str Parameter

Most Western Astrology endpoints (`/natal`, `/transits`, `/synastry`) accept an optional `tz_str` parameter. This parameter controls how the provided local time is interpreted.

ValueBehavior
"AUTO"Recommended. The engine uses the provided latitude/longitude and date to determine the correct timezone. It automatically detects if the date is historical (pre-standardization) and uses LMT if necessary.
"Europe/Paris"Explicit IANA Timezone ID. Forces the engine to use this specific timezone rule.
Warning: Using modern IDs for ancient dates may result in incorrect LMT calculations.
"UTC"Treats the input time as Universal Coordinated Time. Use this only if you have already converted the birth time to UTC yourself.

Common Timezone IDs (IANA)

The tz_str parameter requires a valid Area/Location format. General regions like "US" or "Asia" are NOT supported.

Valid Examples

  • "America/New_York"
  • "America/Los_Angeles"
  • "Europe/London"
  • "Asia/Tokyo"
  • "Asia/Kolkata"
  • "Australia/Sydney"

Invalid (Do Not Use)

  • "US" (Too vague)
  • "EST" (Ambiguous)
  • "Asia" (Not a timezone)
  • "Paris" (Must be Europe/Paris)

Historical Accuracy (LMT)

Before the adoption of Standard Time (late 19th/early 20th century), locations used Local Mean Time (LMT). LMT is strictly determined by longitude: 4 minutes per degree.

When `tz_str="AUTO"` is used:

  • The engine checks the birth year against a database of timezone adoption dates for that region.
  • If the date is pre-standardization, it automatically calculates LMT based on `lng`.
  • If the date is post-standardization, it looks up the explicit offset (including historical war times/DST) for that zone.

Chinese Astrology Standards

Chinese BaZi and Vedic Reference endpoints typically use a refined `time_standard` parameter instead of `tz_str`.

civil

Raw clock time. Matches most standard calendar apps and basic calculators.

true_solar

Recommended for BaZi. Adjusts clock time for your specific longitude relative to the timezone meridian. Essential for correct Hour Pillar calculation.

true_solar_absolute

Pure astronomical solar time (Sundial time). Only used for very specific research purposes.