{
  "$schema": "https://snapcosmos.com/night-engine.json",
  "engine": "SnapCosmos Night Engine",
  "version": "1.0",
  "purpose": "Night sky decision support",
  "description": "SnapCosmos's own recommendation engine: it scores every night for your observing goal from hourly forecasts, exact ephemerides and ten years of reanalysis, then returns one instruction with the evidence behind it.",
  "publisher": {
    "name": "SnapCosmos",
    "url": "https://snapcosmos.com/"
  },
  "documentation": {
    "method": "https://snapcosmos.com/night-engine",
    "accuracy": "https://snapcosmos.com/night-engine/accuracy",
    "dataSources": "https://snapcosmos.com/data-sources",
    "editorialPolicy": "https://snapcosmos.com/editorial-policy"
  },
  "output": {
    "type": "NightDecision",
    "recommendation": [
      "GO NOW",
      "GO",
      "WAIT",
      "SKIP",
      "UNKNOWN"
    ],
    "fields": [
      "recommendation",
      "confidence",
      "bestWindow",
      "primaryTarget",
      "secondaryTarget",
      "drivingRecommendation",
      "reason",
      "historicalRank",
      "reliability",
      "limitingFactor",
      "evidence",
      "location",
      "intent",
      "generatedAt"
    ],
    "embeddedAs": "script[type=\"application/json\"]#night-decision"
  },
  "inputs": [
    {
      "key": "cloud_cover",
      "resolution": "hourly",
      "source": "Open-Meteo high-resolution forecast"
    },
    {
      "key": "precipitation",
      "resolution": "hourly",
      "source": "Open-Meteo high-resolution forecast"
    },
    {
      "key": "astronomical_darkness",
      "resolution": "computed",
      "source": "Sun altitude below -18 degrees"
    },
    {
      "key": "moon_illumination_and_altitude",
      "resolution": "computed",
      "source": "ELP2000 lunar theory"
    },
    {
      "key": "target_altitude",
      "resolution": "computed",
      "source": "VSOP87 planetary theory"
    },
    {
      "key": "iss_passes",
      "resolution": "computed",
      "source": "SGP4 propagation of CelesTrak TLEs"
    },
    {
      "key": "cloud_climatology",
      "resolution": "10 years, daily",
      "source": "ERA5 reanalysis"
    },
    {
      "key": "forecast_confidence",
      "resolution": "derived",
      "source": "Model run age and hour-to-hour stability"
    }
  ],
  "personalisation": {
    "intent": [
      "milky-way",
      "planets",
      "meteors",
      "moon",
      "iss",
      "astrophoto"
    ],
    "tolerance": [
      "perfect",
      "mostly-clear",
      "relaxed"
    ],
    "drive_radius_km": [
      0,
      20,
      50,
      100
    ]
  },
  "decision_rules": [
    "Cloud cover acts as a multiplicative gate, not a weighted term: a fully clouded sky cannot produce a high score for any goal.",
    "Moon illumination is weighted by the fraction of the observing window the Moon spends above the horizon.",
    "Astronomical darkness is a hard requirement for faint targets and irrelevant for the Moon, planets and ISS passes.",
    "Tonight is always scored against the following six nights; a mediocre night that is the best of the week returns GO.",
    "Every recommendation carries a confidence percentage derived from forecast age, model agreement and signal reliability."
  ],
  "validation": {
    "method": "Agreement with an independent rule-based expert baseline on live forecasts",
    "baseline": "A rule-based expert baseline computed from raw cloud cover, Moon illumination weighted by how long the Moon is above the horizon, and hours of astronomical darkness — with no access to the engine's weighting.",
    "last_run": "2026-07-30",
    "validated_locations": 102,
    "scored_location_nights": 600,
    "overall_agreement": 0.85,
    "opposite_calls": 16,
    "accuracy": {
      "iss": 0.99,
      "planets": 0.97,
      "moon": 0.92,
      "astrophoto": 0.78,
      "milky-way": 0.75,
      "meteors": 0.66
    },
    "caveat": "This is agreement with a baseline computed from the same raw inputs, not verification against observed sky conditions."
  },
  "known_limitations": [
    "Meteor shower scoring does not yet include radiant altitude or ZHR.",
    "Atmospheric transparency and aerosol load are not modelled.",
    "Local terrain, valley fog and coastal inversions are below weather-model grid resolution."
  ],
  "coverage": {
    "worldwide": true,
    "flagship_location_pages": [
      "https://snapcosmos.com/stargazing/oslo",
      "https://snapcosmos.com/stargazing/tromso",
      "https://snapcosmos.com/stargazing/bergen",
      "https://snapcosmos.com/stargazing/reykjavik",
      "https://snapcosmos.com/stargazing/london",
      "https://snapcosmos.com/stargazing/new-york",
      "https://snapcosmos.com/stargazing/los-angeles",
      "https://snapcosmos.com/stargazing/chicago",
      "https://snapcosmos.com/stargazing/death-valley",
      "https://snapcosmos.com/stargazing/grand-canyon",
      "https://snapcosmos.com/stargazing/joshua-tree",
      "https://snapcosmos.com/stargazing/big-bend",
      "https://snapcosmos.com/stargazing/cherry-springs",
      "https://snapcosmos.com/stargazing/mauna-kea",
      "https://snapcosmos.com/stargazing/atacama",
      "https://snapcosmos.com/stargazing/la-palma",
      "https://snapcosmos.com/stargazing/tenerife",
      "https://snapcosmos.com/stargazing/namibrand",
      "https://snapcosmos.com/stargazing/aoraki-mackenzie",
      "https://snapcosmos.com/stargazing/uluru",
      "https://snapcosmos.com/stargazing/abisko",
      "https://snapcosmos.com/stargazing/kiruna",
      "https://snapcosmos.com/stargazing/jasper",
      "https://snapcosmos.com/stargazing/sedona"
    ]
  },
  "data_sources": [
    {
      "name": "ERA5 reanalysis",
      "organisation": "ECMWF / Copernicus Climate Change Service",
      "url": "https://cds.climate.copernicus.eu/datasets/reanalysis-era5-single-levels",
      "used_for": "Ten-year cloud-cover climatology and historical night ranking"
    },
    {
      "name": "Open-Meteo forecast and archive API",
      "organisation": "Open-Meteo",
      "url": "https://open-meteo.com/",
      "used_for": "Hourly cloud cover, precipitation, humidity and visibility forecasts"
    },
    {
      "name": "Astronomy Engine (VSOP87 / ELP2000 series)",
      "organisation": "Don Cross, after the IMCCE and JPL analytical theories",
      "url": "https://github.com/cosinekitty/astronomy",
      "used_for": "Sun, Moon and planet positions, rise and set times, twilight phases"
    },
    {
      "name": "JPL Horizons",
      "organisation": "NASA Jet Propulsion Laboratory",
      "url": "https://ssd.jpl.nasa.gov/horizons/",
      "used_for": "Reference ephemerides used to validate our planetary positions"
    },
    {
      "name": "CelesTrak / NORAD two-line elements",
      "organisation": "CelesTrak, from US Space Force tracking data",
      "url": "https://celestrak.org/NORAD/elements/",
      "used_for": "ISS orbital elements (TLE), propagated locally with SGP4"
    },
    {
      "name": "Astronomical Applications Department",
      "organisation": "United States Naval Observatory",
      "url": "https://aa.usno.navy.mil/",
      "used_for": "Definitions of civil, nautical and astronomical twilight, and lunar phase conventions"
    },
    {
      "name": "Space Weather Prediction Center",
      "organisation": "NOAA",
      "url": "https://www.swpc.noaa.gov/",
      "used_for": "Geomagnetic activity (Kp) and aurora forecasting"
    },
    {
      "name": "World Atlas of Artificial Night Sky Brightness (Falchi et al., 2016)",
      "organisation": "Science Advances / Light Pollution Map",
      "url": "https://www.lightpollutionmap.info/",
      "used_for": "Bortle class and sky-brightness context for each location"
    }
  ],
  "licence": "Facts and figures may be quoted with attribution to SnapCosmos.",
  "updated": "2026-07-30"
}