Astronomical time

Meeus, Astronomical Algorithms · checked against USNO and IERS

Preview

The test data isn't published yet; the work is in issue #4. The case count, the expiry date and everything under Test data are made up to show how the finished page will look.

Planned · 4 cases · valid until 2027-12-31

What it is

The sun and moon both stand on these. A calendar date is awkward to do arithmetic with, so astronomy counts days instead: the Julian day is the number of days since noon on 1 January 4713 BC. Clocks keep uniform time, but the Earth’s spin wobbles and slows, and ΔT is the gap between the two, about 69 seconds now and not predictable far ahead. Sidereal time is the Earth’s turn measured against the stars, which says which part of the sky is overhead. With it, any position in the sky becomes two angles for a place on the ground.

An observer at the centre of the horizon, with azimuth measured clockwise from north along the horizon and altitude measured up from it

Test these first. When a sunrise is wrong, these cases say whether the fault is underneath.
ΔT is measured, not computed, so its values expire and the file says when.
A sidereal day is 23 h 56 min 4 s, about 4 minutes shorter than a solar day.

Operations

Operation	Gives
`julianDay`	The Julian day of an instantIn: `instantUtc` Out: `julianDay`
`calendarDate`	The calendar date of a Julian dayIn: `julianDay` Out: `date`, `calendar`
`deltaT`	ΔT for a dateIn: `decimalYear` Out: `deltaTInSeconds`
`siderealTime`	Mean sidereal time at Greenwich and at a longitudeIn: `instantUtc`, `longitudeInDegrees` Out: `greenwichSiderealTimeInHours`, `localSiderealTimeInHours`
`horizontal`	A sky position as azimuth and altitude from a placeIn: `rightAscensionInHours`, `declinationInDegrees`, `latitudeInDegrees`, `longitudeInDegrees`, `instantUtc` Out: `azimuthInDegrees`, `altitudeInDegrees`

Fields

Field	Meaning
`latitudeInDegrees`	−90 to 90, WGS84, north positive
`longitudeInDegrees`	−180 to 180, WGS84, east positive
`instantUtc`	An instant, ISO 8601 in UTC, like 2026-01-01T00:00:00Z
`julianDay`	Days since noon UTC on 1 January 4713 BC, with a fraction
`date`	A calendar date, YYYY-MM-DD, astronomical years (1 BC is 0000)
`calendar`	gregorian from 1582-10-15, julian before
`decimalYear`	The year plus the fraction elapsed
`deltaTInSeconds`	Uniform time minus Earth-rotation time
`greenwichSiderealTimeInHours`	0 to 24
`localSiderealTimeInHours`	0 to 24
`rightAscensionInHours`	0 to 24, a sky position's east–west angle
`declinationInDegrees`	−90 to 90, a sky position's angle north of the celestial equator
`azimuthInDegrees`	0 to 360, clockwise from north
`altitudeInDegrees`	−90 to 90, up from the horizon

Edge cases

Case	What's right
2000-01-01T12:00:00Z	`julianDay` 2451545.0, the J2000 epoch
1582-10-04 to 1582-10-15	The Gregorian calendar starts; the ten days between never happened
Dates before year 1	Astronomical years: 1 BC is year 0
A position below the horizon	A negative `altitudeInDegrees`, not an error

For agents

Follow Meeus, Astronomical Algorithms: chapter 7 for the Julian day, 12 for sidereal time and 13 for coordinate transforms. Use the Gregorian calendar from 1582-10-15 and the Julian before it, with astronomical year numbering. Interpolate deltaTInSeconds from the IERS values the file is built from. Pass every case in vectors.json within its tolerance.

Test data

In vectors.json, published 2026-01-01. Earth model: WGS84. How to read it: Test data format.

Field	Tolerance
`julianDay`	± 0.00001
`deltaTInSeconds`	± 1
`greenwichSiderealTimeInHours`	± 0.0001
`localSiderealTimeInHours`	± 0.0001
`azimuthInDegrees`	± 0.01
`altitudeInDegrees`	± 0.01

Every other field is compared exactly.

Case	Input	Expected
`placeholder-1`julianDay · hand	`instantUtc` "2026-01-01T00:00:00Z"	`julianDay` 1234567.5
`placeholder-2`calendarDate · edge, hand	`julianDay` 1234567.5	`date` "1582-10-15" `calendar` "gregorian"
`placeholder-3`deltaT · reference	`decimalYear` 2026.0	`deltaTInSeconds` 12.3
`placeholder-4`horizontal · reference	`rightAscensionInHours` 1.23 `declinationInDegrees` 45.6 `latitudeInDegrees` 11.11 `longitudeInDegrees` 22.22 `instantUtc` "2026-01-01T00:00:00Z"	`azimuthInDegrees` 123.45 `altitudeInDegrees` 35.67

Implementations

Repo	Status
gshaw/algorithms-swiftSwift	Incomplete

Each is a public repo that runs this page's test data with mise run test. See how implementations work.

Source

Method	Astronomical Algorithms, 2nd edition, 1998Jean Meeus
ΔT	Earth orientation dataIERS · ⚠️ Terms not checked yet
Reference	Astronomical Applications APIUS Naval Observatory · Public domain