Sky.Starlink.Viewer

Is tonight the night? One call, and you'll know.

Starlink trains are only visible in a narrow window — satellites still lit by a sun that's already set for you, in a sky dark enough to see them, on a night that isn't clouded over. Work it out yourself and you're propagating orbits, calculating twilight, and pulling a cloud forecast, then joining all three.

Ask for a place. Get back whether it's worth going outside, and when.

Portland, ME is all it takes. Add days ahead if you want a longer horizon.

Here's what comes back when the answer is no — which is the interesting case, so it's the one worth showing:

{
  "query": { "lat": 43.65737, "lng": -70.2589, "timezone": "America/New_York", "daysAhead": 14 },

  "isVisibleWithinRange": false,
  "recommendedViewing": null,
  "summary": "No Starlink train worth going outside for was found in the next 14 days.",
  "whyNot": [
    "A train was found but conditions during it were not good enough to recommend",
    "Weather conditions were poor during the best pass windows"
  ],

  "upcomingCandidates": [
    {
      "date": "2026-10-06",
      "peakTime": "2026-10-06T19:33:01-04:00",
      "score": 7.5,
      "conditions": "good",
      "forecastConfidence": "low",
      "direction": "NNW -> SSE",
      "maxElevationDeg": 77,
      "satellitesVisibleAtOnce": 4,
      "trainType": "none",
      "estimatedMagnitude": 4.9,
      "cloudCoverPercent": 0,
      "reason": "Pass reaches 77° elevation. Cloud cover forecast is 0%. Sky is dark
                 during the viewing window. 4 satellites - too few for a real train.
                 Look toward the NNW to start; it climbs to about 77° over the WSW and
                 exits to the SSE, roughly 10 min across the sky. Estimated magnitude
                 4.9 - on the faint side - easier in a dark sky"
    }
    /* ...four more, ranked by score */
  ],

  "nextViewing": {
    "date": "2026-09-27",
    "peakTime": "2026-09-27T19:46:20-04:00",
    "conditions": "not viewable",
    "cloudCoverPercent": 100
    /* ...same shape as a candidate */
  },

  "denseTrainsInOrbit": 1,
  "trainsInOrbit": [
    { "trainId": "2026-181-2", "satelliteCount": 5, "altitudeKm": 415, "visibleFromHere": false }
  ],

  "launchCadence": { "launchesPerWeek": 1.87, "daysBetweenLaunches": 3.8 },

  "dataProvidedBy": "Gimmee.info (CelesTrak, Open-Meteo)",
  "dataPullDateTime": "2026-09-27T21:06:36.0484325Z",
  "gimmeeVersion": "v1.0.0"
}

(Trimmed. The full response carries every candidate in full, the recommended pass's detail when there is one, and more per-train data — it's all in the docs.)

isVisibleWithinRange is the field that does the work. One boolean, and it already knows about the orbit, the twilight, the cloud cover and the satellite count. Wire a light to it, a push notification, a cell colour. Nobody has to interpret anything.

When it's false you're not left guessing. whyNot names the reason in sentences you can show a user — here, a train was up there, but the weather wouldn't cooperate. upcomingCandidates hands you the closest things to a yes anyway, ranked, so someone can decide for themselves. That's the difference between an empty result and an answer.

Every pass, recommended or not, carries a reason written to be read out loud: which way to face, how high it climbs, where it exits, how long it's up, and how faint it'll be. Not a code you look up — a sentence you print.

nextViewing is the very next pass, good or bad. Tonight's is fogged in, and it says so plainly instead of pretending there's nothing up there.

forecastConfidence is honesty about the weather half. A few days out is high. Two weeks out is low, and the field says so rather than letting a clean-looking score imply certainty it hasn't got.

trainsInOrbit tells you what's actually up there right now, even when none of it crosses your sky. And launchCadence answers the question that follows every no: when should I check again? Roughly two launches a week, each train dense for about two days. That's the check-back interval, computed, not guessed.

Two sources, and the maths in between. Orbital elements from CelesTrak, so passes are propagated from the current elements rather than a stale table. Cloud cover from Open-Meteo. Twilight we compute ourselves, because the whole trick is the satellite being in sunlight while you're in the dark. Neither source knows about the other, or about your sky. Joining them is the product.

What you get:

• $9/mo
• 1,000 DataGrab calls a month
• Your API key, emailed the moment you check out
• Setup instructions in that same email
• Full docs - read them here - so your agent or your IDE can wire it up without you.

Full integration guide: api.gimmee.io/docs/sky-starlink-viewer.html

Check out. Open the email. Paste the key. Off you go.