Sun

Meeus, Astronomical Algorithms · checked against USNO

Preview

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

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

What it is

Sunrise and sunset are when the top of the sun touches the horizon. The air bends its light, so the sun’s centre is then 0.833° below it. Twilight is the light after sunset and before sunrise, in three steps by how far the sun is below the horizon. Soldiers and sailors plan around them: nautical twilight is when the horizon is still visible.

Bands below the horizon: civil twilight to 6 degrees, nautical to 12, astronomical to 18, then night

Some days have no sunrise. Inside the polar circles the sun can stay up or down all day, and the answer must say so rather than invent a time.
Events are asked for in a window of time, 24 hours from a UTC start, so no time zone is needed.
It builds on astronomical time: the Julian day and the conversion to azimuth and altitude.

Operations

Operation	Gives
`events`	Rise, set, transit and twilight in a windowIn: `latitudeInDegrees`, `longitudeInDegrees`, `startUtc`, `windowInHours` Out: `riseUtc`, `setUtc`, `transitUtc`, `civilDawnUtc`, `civilDuskUtc`, `nauticalDawnUtc`, `nauticalDuskUtc`, `astronomicalDawnUtc`, `astronomicalDuskUtc`, `isAlwaysUp`, `isAlwaysDown`
`position`	The sun's azimuth and altitude from a placeIn: `latitudeInDegrees`, `longitudeInDegrees`, `instantUtc` Out: `azimuthInDegrees`, `altitudeInDegrees`

Fields

Field	Meaning
`latitudeInDegrees`	−90 to 90, WGS84, north positive
`longitudeInDegrees`	−180 to 180, WGS84, east positive
`startUtc`	The window's start, ISO 8601 in UTC
`windowInHours`	The window's length, 24 unless a case says otherwise
`isAlwaysUp`	true when it's above the horizon for the whole window
`isAlwaysDown`	true when it's below the horizon for the whole window
`instantUtc`	An instant, ISO 8601 in UTC
`riseUtc`	The top of the sun reaches the horizon; its centre at −0.833°. null if it doesn't happen in the window
`setUtc`	As rise, going down
`transitUtc`	Highest in the sky
`civilDawnUtc`	Centre at −6°, rising
`civilDuskUtc`	Centre at −6°, setting
`nauticalDawnUtc`	Centre at −12°, rising
`nauticalDuskUtc`	Centre at −12°, setting
`astronomicalDawnUtc`	Centre at −18°, rising
`astronomicalDuskUtc`	Centre at −18°, setting
`azimuthInDegrees`	0 to 360, clockwise from north
`altitudeInDegrees`	−90 to 90, up from the horizon

Edge cases

Case	What's right
Alert, Nunavut, in June	`riseUtc` and `setUtc` null, `isAlwaysUp` true
McMurdo Station in June	`riseUtc` and `setUtc` null, `isAlwaysDown` true
Twilight that never ends	In high-latitude summer, `nauticalDuskUtc` and `nauticalDawnUtc` can be null
A window crossing midnight UTC	Events on both sides

For agents

Follow Meeus, Astronomical Algorithms, chapters 25 and 15. Find events in the window from startUtc for windowInHours, never in a local calendar day. Use −0.833° for rise and set, and −6°, −12° and −18° for twilight. When the sun doesn’t cross an altitude in the window, return null for that time, and set isAlwaysUp or isAlwaysDown. 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
`riseUtc`	± 60 s
`setUtc`	± 60 s
`transitUtc`	± 60 s
`civilDawnUtc`	± 60 s
`civilDuskUtc`	± 60 s
`nauticalDawnUtc`	± 60 s
`nauticalDuskUtc`	± 60 s
`astronomicalDawnUtc`	± 60 s
`astronomicalDuskUtc`	± 60 s
`azimuthInDegrees`	± 0.01
`altitudeInDegrees`	± 0.01

Every other field is compared exactly.

Case	Input	Expected
`placeholder-1`events · reference	`latitudeInDegrees` 11.11 `longitudeInDegrees` 22.22 `startUtc` "2026-01-01T00:00:00Z" `windowInHours` 24	`riseUtc` "2026-01-01T01:23:00Z" `setUtc` "2026-01-01T12:34:00Z" `nauticalDawnUtc` "2026-01-01T00:12:00Z"
`placeholder-2`events · edge, polar	`latitudeInDegrees` 82.5 `longitudeInDegrees` -62.3 `startUtc` "2026-06-21T00:00:00Z" `windowInHours` 24	`riseUtc` null `setUtc` null `isAlwaysUp` true
`placeholder-3`position · reference	`latitudeInDegrees` 11.11 `longitudeInDegrees` 22.22 `instantUtc` "2026-01-01T00:00:00Z"	`azimuthInDegrees` 123.45 `altitudeInDegrees` 12.34

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
Reference	Astronomical Applications APIUS Naval Observatory · Public domain