solarwindow

README

Iceland solar window

This Go package answers one narrow planning question: for a date and coordinate in Iceland, when is the sun above a chosen altitude?

It distinguishes three cases instead of inventing sunrise or sunset times at the edge of the season:

• two threshold crossings;
• sun above the threshold all day;
• sun below the threshold all day.

That matters around midsummer. In Reykjavík the sun still dips below the horizon, but it does not reach the end of civil twilight near the June solstice. “Sunset” and “dark enough to feel like night” are not the same thing.

Use it

package main

import (
	"fmt"
	"time"

	solarwindow "github.com/thingstodoiniceland/iceland-solar-window"
)

func main() {
	date := time.Date(2026, time.June, 21, 0, 0, 0, 0, time.UTC)

	civil, err := solarwindow.Calculate(
		date,
		64.1466,  // Reykjavík latitude
		-21.9426, // Reykjavík longitude
		solarwindow.CivilTwilight,
	)
	if err != nil {
		panic(err)
	}

	fmt.Println(civil.State) // always_above
}

Use solarwindow.ApparentHorizon (-0.833°) for conventional sunrise and sunset. Use solarwindow.CivilTwilight (-6°) when the useful question is whether civil light remains.

Times are returned in UTC. Iceland stays on UTC throughout the year, so there is no seasonal clock conversion.

What the calculation can and cannot tell you

The package follows the fractional-year, equation-of-time and solar-declination approximation published with the NOAA Solar Calculator. It is suitable for planning and comparison, not navigation or safety-critical decisions.

The result is geometric and approximate. It does not model mountains, buildings, cloud cover, visibility or the time needed to reach a location. Near a threshold, check a current local forecast and leave room for conditions.

For the visitor-side question—what Iceland's late summer light is useful for, and what still needs advance planning—see this practical guide to midnight sun experiences in Iceland.

Test

go test ./...

The tests cover Reykjavík near both solstices, the ordering of civil twilight and apparent sunrise on the South Coast, and invalid coordinates.

License

MIT

Documentation

Overview

Package solarwindow estimates when the sun crosses a chosen altitude for Iceland trip-planning tools.

The calculation is intentionally narrow: it returns UTC times for one coordinate and calendar date. Iceland keeps UTC year-round, so callers do not need a daylight-saving adjustment.

Index

• Constants
• type CrossingState
• type Window
  • func Calculate(date time.Time, latitude, longitude, altitudeDegrees float64) (Window, error)

Constants

const (
	// ApparentHorizon is the conventional altitude used for sunrise and sunset.
	// It includes a small allowance for refraction and the solar disc radius.
	ApparentHorizon = -0.833
	// CivilTwilight is the altitude used for the start and end of civil twilight.
	CivilTwilight = -6.0
)

Types

type CrossingState

type CrossingState string

CrossingState describes whether a threshold has two daily crossings.

const (
	// Crosses means the sun rises above and later falls below the threshold.
	Crosses CrossingState = "crosses"
	// AlwaysAbove means the sun remains above the threshold throughout the day.
	AlwaysAbove CrossingState = "always_above"
	// AlwaysBelow means the sun remains below the threshold throughout the day.
	AlwaysBelow CrossingState = "always_below"
)

type Window

type Window struct {
	DateUTC         time.Time
	Latitude        float64
	Longitude       float64
	AltitudeDegrees float64
	State           CrossingState
	Start           time.Time
	End             time.Time
	ApproximateNoon time.Time
}

Window holds the result for a requested solar-altitude threshold. Start and End are populated only when State is Crosses.

func Calculate

func Calculate(date time.Time, latitude, longitude, altitudeDegrees float64) (Window, error)

Calculate estimates the daily UTC window during which the sun is above altitudeDegrees. The implementation follows the NOAA Solar Calculator's fractional-year, equation-of-time, and solar-declination approximation.

Use ApparentHorizon for sunrise/sunset or CivilTwilight for usable civil light. Terrain, cloud, and local obstructions are deliberately not modeled.