Real-time International Space Station tracker. Polls the wheretheiss.at API every 5 s for ISS lat/lon/altitude/velocity/visibility, draws the position on an equirectangular SVG canvas (graticule grid + 30°-stride lat/lon lines, no coastline data shipped), and tells you whether it's actually visible from your location right now.
The "is it visible" check is the interesting bit: just plotting a dot doesn't tell you if you can step outside and see ISS streak across the sky. Three independent conditions have to be true at the same time:
- ISS above your horizon — your subpoint-distance has to fit inside the satellite's footprint cap.
- ISS sunlit — the satellite has to be out of Earth's shadow so its solar panels reflect light back at you. The wheretheiss.at API gives this directly as
visibility: "daylight" | "eclipsed". - Your sky dark enough — the sun has to be at least 6° below your horizon (civil twilight or darker), otherwise the ISS pinpoint is washed out by sky brightness.
All three are computed from the API response + your lat/lon, no external dependencies, no auth, no orbital propagator.
npm run serve # python3 -m http.server 8080
# open http://localhost:8080In iss.js:
haversineKm(lat1, lon1, lat2, lon2)— great-circle distance, used for both the observer-to-subpoint distance and the observer-to-subsolar-point distance.footprintKm(altitudeKm)— the radius on Earth's surface within which the satellite is above someone's horizon. From the geometrycos α = R / (R + h), the cap's angular radius isα, and the surface arc length isR·α. For ISS at 408 km that's ~2222 km.elevationDeg(observerLat, observerLon, subLat, subLon, altitudeKm)— the angle of the satellite above the observer's local horizon. Solves theOEStriangle (Observer-Earth centre-Satellite) using the law of cosines.slantRangeKm(...)— the straight-line distance from observer to satellite.sunAltitudeDeg(observerLat, observerLon, sunLat, sunLon)— the sun's altitude above the observer's horizon, computed from the subsolar point that the API conveniently provides assolar_lat/solar_lon. We use this to decide if the observer's sky is dark enough.visibilityFromObserver(observer, iss)— combines the three conditions above into a single verdict object.
Real "alert me when ISS will pass over Tokyo at 8 PM tonight" services need Two-Line Element sets and the SGP4 orbital propagator. That's ~2000 lines of dense numerical code (or a satellite.js dependency at ~50KB minified) and a fetch to celestrak.com for current TLEs.
This entry sticks to "right now": the live position is queried, the geometry between you and ISS is computed, and you're told whether currently the three visibility conditions hold. Pass prediction is out of scope — for that, heavens-above.com and spotthestation.nasa.gov already do it well.
npm test24 tests in tests/iss.test.js:
- Haversine — identical points → 0; Tokyo↔Kyoto ≈ 360 km; Tokyo↔NYC ≈ 10850 km; antipodal → π·R.
- Bearing — N/S/E/W cardinal directions.
- Footprint — ISS at 408 km → 2222 km; geostationary at 35786 km → 9054 km; degenerate 0 km → 0.
- Elevation — directly overhead → 90°; at footprint edge → 0°; antipode → far below horizon.
- Slant range — overhead = altitude; at horizon =
√(2Rh + h²). - Sun altitude — at subsolar point → 90°; antipode → −90°; 90° away → 0° (sunrise / sunset).
- Combined visibility — overhead + sunlit + observer-night → visible; eclipsed → not visible; far side → not visible; observer in daytime → not visible.
The geometry module has no DOM and no API dependency, so the whole test suite runs under node --test in 70 ms.
- Earth as a sphere. The math uses R = 6371 km. Real Earth is an oblate spheroid; the error on horizon distances is < 0.3% and well under the noise floor of "is the satellite above your horizon."
- Atmospheric refraction not modelled. ISS at very low elevation (< 5°) appears slightly higher than the geometric calculation says, but you can't see it through the atmosphere at those angles anyway.
- No magnitude estimation. Real ISS apparent magnitude depends on phase angle (sun-ISS-observer geometry); we don't compute it. ISS at zenith on a clear night is ~mag −5, brighter than Venus, so when all three conditions are true it's almost always actually visible.
MIT