When to look up

At the foot of this site, a card says something like: "The International Space Station will pass over New York tonight at 7:13 pm: bright, 6 minutes long. Look northwest, and follow it east." It's the one feature here that's useful away from the screen, and it's mostly geometry.

When the ISS is visible

You can see the station only when three things are true at once:

• It's above your horizon, by at least 10 degrees, clear of trees and buildings
• It's in sunlight, not in the Earth's shadow; it shines by reflected sunlight
• Your sky is dark: the Sun is at least 6 degrees below your horizon

The second and third pull against each other, which is why passes cluster in the hour or two after dusk and before dawn: the ground is in darkness while the station, 400 km up, still catches the Sun.

Where the station is

Its orbit is published as a TLE, two lines of numbers from CelesTrak, updated several times a day. Turning that into a position at a given moment is what the SGP4 model does, and satellite.js implements it. Checked against a live tracker, the predicted position was within 0.1 degrees. The route fetches the TLE at most every 12 hours and keeps it in Redis; if CelesTrak is down, an older one stays good for days.

Where the Sun is

The Sun's position comes from the standard low-precision series (its mean longitude and anomaly, corrected for the orbit's eccentricity), good to a fraction of a degree, which is plenty when a pass lasts minutes. That gives two things: how high the Sun is where you stand, and its direction for the shadow test. The Earth's shadow is modelled as a cylinder behind the planet: the station is lit if it's on the sunward side, or far enough from the shadow's axis.

Finding the passes

for every 20 seconds over the next 5 days:
  station position (SGP4) → elevation and bearing from you
  visible = elevation ≥ 10° and station sunlit and Sun ≤ −6°
group visible moments into passes, drop any under a minute
for each: start, peak, end, highest elevation,
          where it appears and where it goes

That's about 21,600 positions, and it takes 5 to 25 milliseconds. Brightness is estimated from the highest elevation (overhead passes are nearer and brighter), not computed as a magnitude.

Where you are

Location comes from the headers Vercel adds after placing a visitor by IP, the same ones the contact section's globe uses; nothing about the visitor is stored. IP location is only city-level, but at city scale the times shift by seconds and the directions not at all. Times are shown in your own time zone, and "Add to calendar" saves the pass as an event that starts five minutes early, with a reminder.