Sunrise and sunset outlook

Every sunrise and sunset of the next five days at a point, scored twice, for a colourful sky and for a clear view of the sun.

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.

parameter
`lat`	latitude, -90 to 90. Required
`lon`	longitude, -180 to 180. Required

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.

field
`available`	`false` when the point is outside every forecast grid. The other fields are then `null`, empty or `false` (`horizon_days` stays 5), still with a `200`
`lat`, `lon`	the centre of the NBM forecast cell that was scored, not the point you asked for. Everyone asking about the same town reads the same cell
`time_zone`	the point’s own IANA zone
`today`	today’s date at the point, so a client elsewhere can say “today” and “tomorrow” by the place’s calendar
`domain`	the forecast domain: `co` (the lower 48 and the edges of Canada and Mexico), `ak`, `hi`, `pr` (with the Virgin Islands) or `gu` (with the Northern Marianas). See coverage
`sky_alerts`	whether wxalerts.org sends sunrise and sunset notifications for a place saved here. Currently `co`, `ak` and `pr`; Hawaii and Guam are scored but not alerted
`horizon_days`	how many days are covered: today and the next four, by the place’s calendar
`events`	every sunrise and sunset still ahead in that horizon, soonest first. One that has already happened today is not listed
`no_events`	days with no sunrise or no sunset at all, as `{ "kind", "local_date", "reason" }` with `reason` `polar_night` (the sun stays down) or `polar_day` (it stays up). Empty everywhere but the far north

Each event:

field
`kind`	`sunrise` or `sunset`
`local_date`	the date of the event at the point
`event_time`	the instant, UTC
`event_clock`	the same instant on the place’s clock, ready to show
`score`, `category`, `reasons`	the colour score, its category, and plain words for what made it, best first
`clear_score`, `clear_category`, `clear_reasons`	the clear sun score, the same way. `clear_reasons` can be empty
`confidence`	`high`, `medium` or `low`. See confidence
`source`	`HRRR` or `NBM`, the model whose cloud the event was scored from
`lead_hours`	hours from that model’s run to the event
`best_colour`, `best_clear`	the one event per score most worth going out for. At most one of each is `true`, and neither when nothing reaches Fair

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.

score	category
below 25	`poor`
25 to below 50	`fair`
50 to below 75	`good`
75 and up	`great`

Confidence

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

source	used to	confidence
HRRR cloud layers	6 hours lead (to 48 if no NBM data is on hand)	`high` to 6 hours, `medium` to 18, `low` beyond
NBM cloud layers (lower 48 only)	36 hours lead	`high`
NBM total cloud	the rest of the horizon	`medium` to 60 hours, `low` beyond

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.