Rozhen Observing Planner

• Sun and Moon from Meeus' Astronomical Algorithms: low-precision solar position (~1′) and a truncated lunar series (~0.3°). Rise/set use the standard horizons (−0.833° Sun, +0.125° Moon); times are good to a minute or two, which is all a plan needs.
• Target altitude is plain spherical trigonometry from the coordinates precessed to the date (Meeus 21.3) and local sidereal time, every 5 minutes; airmass is Kasten & Young. Nutation, refraction at the target and proper motion are left out: together under 3′ for anything above 20°, nothing on a chart whose fields are degrees wide. Altitudes shown are geometric.
• Cross-checked against astropy (ERFA) on 24 dates from 1962 to 2037 in the test suite: Sun within 1′, Moon within 0.5°, star altitudes within 0.1°, precession within 10″, sidereal time within 2 s, and the computed sunset / astronomical-dark moments put astropy's Sun at −0.833° / −18° within 2′. astropy is a test dependency only — the planner itself stays standard library.
• Three marks. Astronomy multiplies darkness × target altitude × moonlight (illumination × closeness × height) per 5 minutes and integrates over the night, scaled by the peak; 100 = four hours at perfect geometry, and ten marginal hours cannot pass for a perfect night. Weather is the cloud factor (1 − cover/90, zero at ≥ 80 %) weighted by when the sky is actually useful for this target. Overall = astronomy × weather — and simply Unknown when there is no forecast or history, so a fine geometry is never mistaken for a promise of a clear night. Cloud ≥ 80 % zeroes a sample outright; the Moon only dims. The reasons line says which factor cost the most. Calculation version 2026-10-10.1.
• Names go to CDS Sesame (SIMBAD / NED / VizieR). Solar-system bodies are not resolved — give coordinates for the night from JPL Horizons.
• Weather is Open-Meteo: the hourly model forecast at the observatory's coordinates and altitude for the coming 4 days (refreshed every 30 minutes), and for past nights the ERA5 reanalysis — hourly cloud cover reconstructed from observations, 1940 onwards, about 5 days behind real time. Mountain weather is local; neither knows about the Rhodope fog in the valley below.

All times are local (Europe/Sofia). The night runs from local noon to the next local noon.

curl -sS "https://devops.majbase.com/rozhen-planner/api?target=M31&date=2026-09-18"
curl -sS "https://devops.majbase.com/rozhen-planner/api?target=83.63+22.01"      # RA Dec in degrees
curl -sS "https://devops.majbase.com/rozhen-planner/api"                          # just the night (Sun, Moon, clouds)

Response shape

{
  "night_date": "2026-10-09",
  "site": {"name": "NAO Rozhen", "lat": 41.693, "lon": 24.739, "elev_m": 1750},
  "night": {"sunset": "…Z", "sunrise": "…Z", "twilight": {"civil": {…}, "nautical": {…}, "astronomical": {…}},
            "dark_from": "…Z", "dark_to": "…Z", "dark_hours": 9.55,
            "moonrise": "…Z", "moonset": "…Z", "moon": {"illumination": 0.007, "phase": "new moon", "waxing": false},
            "moon_free_dark_hours": 9.55},
  "target": {"ra": 10.68, "dec": 41.27, "ra_of_date": 11.03, "dec_of_date": 41.41,
             "transit": {"t": "…Z", "alt": 89.6, "az": 187.9, "airmass": 1.0},
             "good_hours": 9.58, "usable_hours": 9.58, "moon_separation": 144.4,
             "verdict": "good", "summary": "…", "resolved": {"name": "M31", "common_name": "Andromeda Galaxy", "type": "AGN"},
             "track": [{"t": "…Z", "alt": 12.3, "az": 41.0, "airmass": 4.6}, …]},
  "assessment": {"score": 84, "verdict": "good", "headline": "Worth it",
                 "score_astronomy": 92, "verdict_astronomy": "good", "score_weather": 71, "weather_known": true,
                 "quality_hours": 3.4,
                 "best_window": {"label": "good", "start_local": "22:30", "end_local": "02:15", "hours": 3.75, "mean_quality": 0.82},
                 "windows": [{"label": "marginal", "start_local": "20:30", "end_local": "22:30", …}, …],
                 "hourly": [{"time": "21:00", "sky": "night", "alt": 45, "moon_alt": -12, "cloud": 20, "low": 5, "mid": 0, "high": 20,
                             "rh": 71, "wind": 9.4, "precip": 0, "temp": 6.1, "q": 0.78, "label": "good"}, …],
                 "reasons": ["cloud cover cost 2.1 quality-hours"], "hard_limit": null, "cost": {…}},
  "forecast": [...hourly rows...], "forecast_source": "forecast", "forecast_updated_at": "…Z",
  "calculation_version": "2026-10-10.1", "warnings": []
}

Three marks: score_astronomy (darkness × altitude × Moon, always known), score_weather (clouds over the dark hours; null without a forecast or history) and score, the overall — null with verdict: "unknown" when the weather is not known, never a geometry-only number dressed up as a promise. Errors: {"error": "…", "code": "target_unresolved"} with HTTP 400 when a target is given but cannot be resolved; an unparseable date is not an error — tonight is used and a warning is added. date is the evening the night starts on, as 2026-10-09, 2026.10.09 or 09.10.2026; omitted = tonight. The response carries night (sunset/sunrise, twilights, dark window, Moon), target (coordinates, transit, dark hours above the limits, Moon separation, verdict of good / marginal / poor / none / never, and the 5-minute track of altitude, azimuth and airmass) and forecast (hourly rows for the night). Times are ISO 8601 UTC.