Sunrise and sunset outlook

Base URL: https://api.wxalerts.org

How good each coming sunrise and sunset will look at a point, from the same forecast that drives the wxalerts.org sunrise and sunset notifications. Every event gets two scores from 0 to 100: one for colour in the sky, one for whether the sun’s own disc will be visible down to the horizon.

GET /sky/outlook?lat=35.2&lon=-97.4

No key needed. Browsers block calls from other websites (CORS allows only wxalerts.org), so call it from a server, script or app. Responses carry Cache-Control: public, max-age=900: scores are kept for a quarter of an hour, and a new model hour lands about hourly. Limits are on the overview.

There is no place name or location_id form. A missing or out of range coordinate is a 422.

What a response holds

{
  "available": true,
  "lat": 35.208,
  "lon": -97.365,
  "time_zone": "America/Chicago",
  "today": "2026-11-09",
  "domain": "co",
  "sky_alerts": true,
  "horizon_days": 5,
  "events": [
    {
      "kind": "sunset",
      "local_date": "2026-11-09",
      "event_time": "2026-11-09T23:28:41.527566Z",
      "event_clock": "5:28 PM CST",
      "score": 79.0,
      "category": "great",
      "confidence": "high",
      "reasons": ["broken mid and high cloud to catch the colour", "a clear horizon toward the sun"],
      "clear_score": 44.5,
      "clear_category": "fair",
      "clear_reasons": ["cloud along the sun's path may hide it"],
      "source": "NBM",
      "lead_hours": 6.5,
      "best_colour": true,
      "best_clear": false
    },
    {
      "kind": "sunset",
      "local_date": "2026-11-10",
      "event_time": "2026-11-10T23:27:55.018498Z",
      "event_clock": "5:27 PM CST",
      "score": 14.7,
      "category": "poor",
      "confidence": "high",
      "reasons": ["mostly clear sky overhead", "a clear horizon toward the sun"],
      "clear_score": 99.1,
      "clear_category": "great",
      "clear_reasons": ["a clear line of sight to the horizon"],
      "source": "NBM",
      "lead_hours": 30.5,
      "best_colour": false,
      "best_clear": true
    },
    "..."
  ],
  "no_events": []
}

The second event above is the usual trade: a cloudless evening is a poor colour sunset and a near perfect clear sun.

Each event:

How the scores work

Colour

The colour score asks whether the low sun will light up cloud from below. It is the product of five factors, times 100, clamped to 0 to 100:

• Canvas. Mid and high cloud overhead for the sun to light. A broken deck (about 30% to 70% cover) is best and scores the full factor. A clear sky still glows a little (0.15 of full); a solid overcast is dull (0.45).
• Local low cloud. A low deck overhead (base below 2 km) hides the show from the observer.
• Light path. The light has to reach the canvas. Low cloud, a near solid mid deck or rain between you and the horizon, sampled 25 to 300 km toward the sun, blocks it. In the lower 48, so can terrain: the ground toward the sun is checked against a ray to the canvas through the colour window, from sunset until the sun is two degrees down.
• Haze. A little aerosol warms the colours and can lift the score slightly; thick smoke, fog or murk mutes them.
• Rain at the observer, from the chance of precipitation.

Clear sun

The clear sun score asks the opposite question: will the disc itself be visible right down to the horizon? A cloudless sky is its best case, which the colour score rates Poor by design. It multiplies four factors:

• Low cloud overhead. Fog or a low deck hides the sun outright.
• The sun line. Cloud at every level along the path toward the sun, with the nearest points weighted most. Thin high cloud counts for part, since it often lets a dimmed disc through.
• Haze. Light haze only reddens the disc; thick smoke or murk hides it.
• Rain at the observer.

Terrain does not count against it: a sun setting behind a ridge is still a clear sun, only earlier.

Categories

Both scores share the same categories.

Confidence

Each event is scored from the first source that has data for it and is within its lead:

Both NBM sources report as NBM in source. Total cloud is placed low or high by the forecast ceiling; where there is no ceiling, which is most of the horizon past three and a half days, confidence is low. A light path that is mostly unknown (it runs off the grid, as it does out to sea from Guam and Puerto Rico) costs one level.

The best event

best_colour and best_clear pick the highest score after weighting by confidence (high 1.0, medium 0.85, low 0.7), so a day four guess at 90 does not outrank a confident 75. Ties go to the sooner event. Nothing scoring below 25 is picked.

Coverage

Anywhere inside one of the five NBM domains. Outside the lower 48 there is only NBM total cloud, no smoke or aerosol and no terrain, so an event there is medium confidence at best. A point outside every grid returns "available": false.