Skip to content

Solar Time API

Compute true apparent solar time for any coordinate on Earth.

GET /solar

Returns the current true solar time for a given location.

Parameters

Parameter Required Type Description
lat ✅ float Latitude (−90 to +90)
lng ✅ float Longitude (−180 to +180)
utc No string UTC timestamp (ISO 8601). Defaults to current time.
alt No number Observer altitude in meters above sea level (default: 0, range: -500 to 100000)
refraction No boolean Enable atmospheric refraction correction (default: true)
temp_c No number Ambient temperature in Celsius for refraction (default: 10.0, range: -89 to 57)
pressure_hpa No number Atmospheric pressure in hPa for refraction (default: 1013.25, range: 100 to 1100)

Example

curl "http://localhost:8090/solar?lat=51.5074&lng=-0.1278"

Response

{
  "latitude": 51.5074,
  "longitude": -0.1278,
  "utc": "2026-04-14T12:00:00Z",
  "solar_time": "2026-04-14T11:49:23",
  "civil_time": "2026-04-14T13:00:00+01:00",
  "equation_of_time_min": -10.6,
  "civil_solar_offset_min": -10.6,
  "timezone": "Europe/London",
  "solar_noon_utc": "2026-04-14T12:10:37Z",
  "sunrise_utc": "2026-04-14T05:42:11Z",
  "sunset_utc": "2026-04-14T19:39:04Z"
}

Response Fields

Field Type Description
solar_time string True apparent solar time (local, no timezone suffix)
civil_time string Civil clock time with UTC offset
equation_of_time_min float Equation of time in minutes (Sun fast/slow vs mean)
civil_solar_offset_min float Minutes civil clock leads (+) or lags (−) the Sun
solar_noon_utc string UTC time of solar noon today
sunrise_utc string UTC time of sunrise
sunset_utc string UTC time of sunset
refractionModel string Refraction model used (e.g., "standard" or "none")
altitudeMeters number Observer altitude in meters used for the calculation

GET /solar/reform

Shows the civil-solar offset under different timezone reform scenarios (e.g., abolishing DST, shifting to permanent summer time).

Parameters

Parameter Required Type Description
lat ✅ float Latitude
lng ✅ float Longitude
scenario No string current, permanent_summer, permanent_winter, solar

Example

curl "http://localhost:8090/solar/reform?lat=40.41&lng=-3.70&scenario=permanent_summer"

Response

{
  "location": {"lat": 40.41, "lng": -3.70},
  "scenarios": {
    "current": {"civil_solar_offset_min": -28, "description": "Current DST rules"},
    "permanent_summer": {"civil_solar_offset_min": -88, "description": "UTC+2 year-round"},
    "permanent_winter": {"civil_solar_offset_min": -28, "description": "UTC+1 year-round"},
    "solar": {"civil_solar_offset_min": 0, "description": "True solar time zone"}
  }
}

GET /solar/ical

Returns an iCalendar (.ics) feed of solar events (sunrise, sunset, solar noon) for a given location.

Parameters

Parameter Required Type Description
lat ✅ float Latitude
lng ✅ float Longitude
year No int Calendar year (e.g., 2026). Defaults to the current year.

Example

curl "http://localhost:8090/solar/ical?lat=51.5&lng=-0.1" -o solar.ics

Subscribe in any calendar app (Google Calendar, Apple Calendar, Thunderbird) by adding the URL as a calendar subscription.