Methodology and accuracy
This page explains how every number on Heliotempo is calculated, which data it relies on, and how accurate it is. If anything is unclear or you find an error, please get in touch.
Sun position
Sun positions are calculated with Astronomy Engine (by Don Cross, MIT licence), an open-source library that models the orbits of the Earth and planets, precession, nutation, aberration and Earth’s rotation including Delta T. Its positions are verified against the NOVAS C 3.1 software of the US Naval Observatory and against NASA JPL’s Horizons system, and agree to within about one arcminute.
The apparent elevation of the sun includes standard atmospheric refraction. Azimuth is measured clockwise from true (geographic) north.
For charts that need thousands of positions (yearly daylight charts, heatmaps, map overlays, 3D views), a faster formula set based on the NOAA solar calculator and Jean Meeus’s Astronomical Algorithms is used. It agrees with Astronomy Engine to about 0.05° in position and about one minute in time. Times shown as text always come from Astronomy Engine.
Definitions
| Event | Definition (centre of the sun) |
|---|---|
| Sunrise, sunset | 0.833° below the horizon (upper edge of the disc on a sea-level horizon, with standard refraction) |
| Civil dawn, dusk | 6° below the horizon |
| Nautical dawn, dusk | 12° below the horizon |
| Astronomical dawn, dusk | 18° below the horizon |
| Golden hour | from 6° above to 4° below the horizon |
| Blue hour | from 4° to 6° below the horizon |
| Solar noon | the sun crosses the local meridian (hour angle 0) |
| Day length | time from sunrise to sunset |
Twilight and golden-hour limits use the geometric position of the sun’s centre, as is conventional. Solstices and equinoxes are the moments when the sun’s apparent ecliptic longitude reaches 90°, 180°, 270° and 0°.
The calculations assume a flat horizon at sea level. Hills, mountains and buildings delay sunrise and advance sunset; a high viewpoint does the opposite. See the guide How sunrise and sunset are calculated.
Time zones
Local times use the IANA time zone database through your browser’s built-in internationalisation support. Daylight saving time is applied automatically according to the rules in force for each place and date. For locations picked on the map, the time zone is found from time zone boundary data (tz-lookup, based on the timezone-boundary-builder project).
Places and maps
- Place search uses GeoNames data for all places with at least 15,000 inhabitants, © GeoNames, licensed under CC BY 4.0. The search runs entirely in your browser on data served by Heliotempo.
- Maps use vector tiles from OpenFreeMap, based on OpenMapTiles, with map data © OpenStreetMap contributors (ODbL). Building heights for the 3D view come from OpenStreetMap.
- Terrain in the 3D map comes from Mapterhorn.
- The world map outline comes from Natural Earth (public domain).
Shading, balconies and gardens
The house, balcony and garden tools check, every few minutes of a day, whether the sun is above the horizon and whether its direction is blocked:
- A wall receives direct sun when the sun is less than 90° to either side of the direction the wall faces.
- Obstacles (buildings opposite, fences, walls, hedges and trees) are modelled as blocks with a direction, distance, height and width. They block the sun when it is lower than the angle to their top edge in their direction.
- A balcony or roof overhang blocks the sun when the sun’s profile angle (its height measured in the plane perpendicular to the wall) is higher than the angle from the bottom of the opening to the edge of the overhang. Side walls of a recessed balcony limit the sideways angle.
- Monthly values use the 15th of each month. Trees are treated as solid.
These are simplified models: they do not include reflected light, the shape of individual trees, or terrain.
Building shadows on the 3D map
Building shadows are an approximation: each building footprint is shifted away from the sun by its height divided by the tangent of the sun’s elevation, and joined with the original footprint. Heights come from OpenStreetMap and may be missing or estimated. Terrain is not taken into account for shadows.
Solar panels
The solar panel tool uses a typical-weather model. For each month, a clearness index that depends on latitude (the typical ratio of global sunlight at the ground to sunlight at the top of the atmosphere) sets how much light reaches the ground. The Erbs correlation splits it into direct and diffuse light; through the day, direct light follows the shape of a clear-sky beam (Meinel model with the Kasten–Young air mass), so it is weak when the sun is low. On the tilted plane, diffuse light is treated as coming evenly from the whole sky (isotropic model), and ground-reflected light uses an albedo of 0.2. Everything is summed every 15 minutes on every fourth day of the year, and the best tilt is found by trying every whole degree from 0° to 90°. For Berlin this gives a best tilt of about 38° and a flat panel at about 86% of the best, within a few percent of PVGIS. The results are shown as a share of the best orientation and as yearly irradiation in kWh/m². They are not a production forecast: the weather is a smooth average for the latitude rather than local records, and temperature, shading and system losses are ignored. For planning a real system we recommend PVGIS by the European Commission’s Joint Research Centre.
Testing
Heliotempo’s calculations are covered by automated tests that run on every change:
- sunrise and sunset for 8 places on 6 dates, compared with an independent implementation of the NOAA equations (tolerance 2 minutes; the observed agreement is within one minute),
- sunrise and sunset compared with published almanac times for London and New York,
- polar day and polar night, days without astronomical night, daylight saving time changes, seasons, the equation of time and the 2 August 2027 total solar eclipse,
- the fast chart formulas against the exact ones.
Accuracy in practice
- Sun positions: better than 0.02° (exact), about 0.05° (charts).
- Sunrise and sunset: calculated to well within a minute. The real observed time can differ by a minute or more because refraction varies with the weather, and by much more with an obstructed horizon or a high viewpoint.
- Near the polar circles, where the sun moves along the horizon at a shallow angle, small changes in refraction can shift sunrise and sunset by several minutes, and decide whether the sun sets at all.
Last updated September 23, 2026