How MoonScan decides tonight is worth it

1. What the score is

The 0–100 score answers a practical question: how convenient is it to see the Moon from here during this hour? It is not a measure of astronomical importance, transparency, seeing, light pollution or photographic quality. A high score can still be a mediocre view through a telescope.

Cloud clarity is 100 − cloudCover − 0.35 × precipitationProbability, clamped to 0–100. Moon altitude uses clamp((altitude − 3) / 42, 0, 1) × 100 × (0.8 + 0.2 × illumination). Darkness is 100 at or below −18° solar altitude, 0 at or above −6°, and linear in between.

2. Hard gates and caps

• Moon below the horizon: 0.
• Illumination below 0.5%: effectively a new Moon, 0.
• Daylight window: score capped at 55 and labelled daylight. The Moon can be visible by day; the score simply reflects lower contrast.
• Twilight window: capped at 75.
• Full Moon is not automatically best. Illumination slightly increases naked-eye visibility, but head-on sunlight reduces crater contrast. The current score is a general visibility index; a crater-detail mode is not yet implemented.

3. Choosing the best window

MoonScan samples the next 24 hours on the hour. It looks for contiguous runs where the Moon is above 1° and the score is at least 50. A qualifying window must last at least two consecutive hours. Windows are ranked by mean score, with longer windows preferred when scores are within four points. If no two-hour run qualifies, a single hour scoring at least 55 is reported as a short window; otherwise the page explicitly says there is no useful window.

The recommendation score is the mean of the chosen window, rounded. The window start and end are local times for the selected IANA time zone, including daylight-saving transitions. Polar cases where the Moon does not rise or set within the search horizon are reported as such rather than forced into a normal night.

4. Weather and the fallback

Cloud cover, precipitation probability and temperature come from the Open-Meteo hourly forecast. Requests use UTC unix timestamps so there is no ambiguity around local time. Responses are cached at the edge for up to 20 minutes. Forecast values are matched to the nearest hour within 90 minutes; a missing value is never replaced with an assumed clear sky.

If weather is unavailable, or cloud is missing for a particular hour, the score renormalises to astronomy only: 64% altitude + 36% darkness. It is labelled Astronomy only and the weather card says Weather unavailable. An astronomy-only score is never described as weather-adjusted.

5. Astronomy and time

Moon phase, illumination, topocentric altitude and azimuth, and rise/set times come from Astronomy Engine (MIT). Horizontal coordinates use atmospheric refraction. Rise/set searches account for the standard apparent horizon. Phase names use conventional 45° bands around the eight principal phases; the displayed illumination is the calculated illuminated fraction, not a label approximation.

Local times are derived from the location's IANA time zone using the runtime's time zone database. Conversion is iterative around offset changes, so daylight-saving transitions are handled for the times shown. Time zone boundaries are political and can differ from the nearest-city lookup, especially near borders; the selected time zone is always displayed.

The Moon disc is phase-correct. The terminator geometry is derived from the phase angle, and the complete disc is mirrored for the southern hemisphere. Surface texture, libration and the parallactic angle are schematic. The page says so next to the disc.

6. Location and privacy

Manual city search is the default. Geocoding uses Open-Meteo's GeoNames-backed service, cached for a day. Browser geolocation is requested only after an explicit button press and is used once to resolve a time zone. Coordinates are rounded to 0.01° (roughly 1 km) before being placed in the URL or a first-party cookie. MoonScan has no accounts, no advertising and no third-party analytics script. Display preferences are stored in the same cookie mechanism.

9. Known limitations

• Forecasts are uncertain, especially beyond 12 hours. The score is not a guarantee of clear sky.
• Light pollution, haze, local obstructions and the observer's eyesight are not modelled.
• Surface detail is schematic; this is not a photographic lunar atlas.
• Eclipses and planetary conjunctions are intentionally omitted until location-specific visibility is validated.
• The current phase name bands are conventional, so“Full Moon” can appear for several hours around the exact instant.
• No push alerts or accounts exist. A saved reminder requires infrastructure that v1 deliberately avoids.
• The score can be recomputed for any hour and is covered by unit tests; displayed values depend on the forecast snapshot used for that request.