1. Resolve a place without sending birth details
The place picker searches a bundled GeoNames cities1000 snapshot inside the browser. The dataset contains 170,758 place records split into 246 country shards, so the interface can distinguish duplicate place names by country, region and WGS84 coordinates without calling a geocoding service. A manual latitude, longitude and IANA-timezone path remains available when the place is absent or the user needs to correct the selection.
The current dataset snapshot is dated 17 August 2026 and is attributed under CC BY 4.0. Selecting a place supplies coordinates for Rising and an input to the embedded timezone-boundary resolver; it is not treated as an identity field or saved profile.
2. Convert a local clock label to real UTC instant(s)
A written local time is not yet an astronomical instant. The selected coordinates resolve an IANA timezone through tzf-wasm 1.2.4 with embedded boundary data 2026c. Native Temporal is preferred, with @js-temporal/polyfill 0.5.1 as the lazy fallback. The engine then applies the historical offset for the selected date.
When clocks move backward, one local label may identify two real instants. The calculator displays both offsets instead of silently choosing one. When clocks move forward, a label may never have existed; the interface rejects it rather than shifting it. An unknown-time calculation enumerates the valid instants across the complete local civil date, so a 23-hour, 25-hour or historically skipped date is not treated as an ordinary 24-hour day.
3. Calculate geocentric tropical longitudes
Astronomy Engine 2.1.19 supplies the production astronomy primitives. The Moon uses its geocentric ecliptic position. The Sun and planets use a light-time-corrected vector from Earth with aberration enabled, converted from the J2000 equatorial frame to the true ecliptic and equinox of the requested date. The result is normalized to an unrounded longitude from 0 up to, but not including, 360 degrees.
Rising is a local angle rather than a planet. The project calculates the eastern intersection of the local horizon and true ecliptic using sidereal time and the selected coordinates. It does not calculate houses. The accepted initial Rising range is latitude 66 degrees south through 66 degrees north inclusive; outside that range, Rising returns an explicit unsupported state while eligible planets can still calculate.
4. Classify before display rounding
The unrounded 0–360-degree longitude is divided into twelve equal 30-degree intervals beginning with Aries at 0 degrees. Sign classification happens before the interface formats degrees and minutes. A rounded display such as 30°00′ can therefore never push the underlying value into a different sign.
Positions within 0.10 degrees of an interval edge receive a boundary warning. That warning is not a separate cusp sign; it tells the user that input uncertainty or a difference in calculation convention deserves attention.
5. Treat exact, approximate and unknown time differently
Exact time evaluates the explicitly confirmed instant. Approximate time evaluates the full plus-or-minus window: Moon and planets are sampled every 15 minutes and Rising every minute. Unknown time evaluates eligible planets every 30 minutes across the complete local date and omits Rising. A midpoint, noon or midnight is never substituted as the birth time.
If every evaluated position remains in one sign, the result reports that stable sign and the observed degree span. If a sign changes, every possible sign is shown and the transition is refined to one second. The audit records the interval, sample count, cadence, timezone decisions, engine version, method and unrounded exact longitude where one instant was selected.
Versions, validation and change control
Calculator version 0.18.3 pins Astronomy Engine 2.1.19, tzf-wasm 1.2.4, boundary data 2026c, the Temporal polyfill 0.5.1 and the GeoNames cities1000 snapshot dated 17 August 2026. A dependency or data update requires the relevant civil-time, place, Moon, Rising and planetary tests to pass again.
The retained golden set contains 26 global Moon/Rising fixtures producing 52 comparisons, 78 Sun/Venus/Mars comparisons and 156 Mercury-through-Pluto comparisons: 286 independent reference comparisons in total. Planetary longitudes must remain within 0.05 degrees of Swiss Ephemeris 2.10.03 validation output. Swiss Ephemeris is used only in the separate test environment; no Swiss code or ephemeris file ships in the product.
- The retained independent reference suite contains 286 astronomical comparisons.
- Calculation, civil-time and place-data changes are tested before publication.
- Change log: 18 August 2026 — published the first complete method, version and validation record.