Pass Prediction

A satellite pass is the window of time when a satellite is above your local horizon — when you can see it, receive its signals, or communicate through it. Craft predicts passes by propagating the satellite’s orbit forward in time and finding when it rises above a configurable minimum elevation at your observer location.

The anatomy of a pass

Every pass has three key moments:

Event	Abbreviation	Meaning
Acquisition of Signal	AOS	The satellite rises above minimum elevation. This is when your antenna can first “see” it.
Time of Closest Approach	TCA	The satellite reaches its highest point in the sky (maximum elevation). This is when the signal path is shortest and signal strength is typically best.
Loss of Signal	LOS	The satellite drops below minimum elevation. Your antenna loses line-of-sight.

Each event includes an azimuth reading (compass bearing, 0-360 degrees) and the TCA also includes the peak elevation angle.

Note

The names AOS and LOS come from spacecraft tracking terminology. Even if you are tracking visually rather than by radio, the same geometry applies — AOS is when the satellite clears your horizon, LOS is when it drops below it.

Predicting passes from the UI

Select any satellite and open the pass prediction panel. Craft shows upcoming passes for the next 24 hours by default, with columns for:

• AOS time and azimuth
• TCA time, elevation, and azimuth
• LOS time and azimuth
• Total pass duration
• Maximum elevation reached

Higher-elevation passes are generally more useful — the satellite is closer to overhead, the signal path through the atmosphere is shorter, and you have a wider window for communication or observation.

Predicting passes from the API

The passes endpoint accepts a NORAD ID and returns structured pass data:

# ISS passes for the next 24 hours, minimum 5 degrees elevation
curl "https://your-domain/api/passes?sat=25544&hours=24&min_el=5"

Parameters

Parameter	Default	Description
sat	required	NORAD catalog ID
hours	24	Prediction window (max 168 — one week)
min_el	5.0	Minimum peak elevation in degrees

Response structure

{
  "observer": "Home",
  "satellite": "ISS (ZARYA)",
  "norad_id": 25544,
  "count": 4,
  "passes": [
    {
      "satellite_name": "ISS (ZARYA)",
      "norad_id": 25544,
      "aos_time": "2026-02-14T19:23:41Z",
      "aos_az": 215.3,
      "tca_time": "2026-02-14T19:28:12Z",
      "tca_alt": 62.4,
      "tca_az": 135.8,
      "los_time": "2026-02-14T19:32:44Z",
      "los_az": 48.1,
      "duration_seconds": 543.0,
      "max_elevation": 62.4,
      "is_visible": true
    }
  ]
}

There is also a convenience endpoint for just the next pass:

curl "https://your-domain/api/passes/next?sat=25544"

Minimum elevation filtering

The min_el parameter controls which passes are returned. A pass is only included if its TCA (peak elevation) exceeds this threshold.

Why filter by elevation?

• Passes below about 5 degrees are nearly on the horizon, where buildings, trees, and terrain block the signal path
• Atmospheric attenuation is much worse at low elevation angles
• Your rotor may have physical limits that prevent pointing near the horizon

The default minimum is 5 degrees. For VHF/UHF satellite work, 10-15 degrees is a practical threshold. For visual observation, even lower angles can work on a clear horizon.

Tip

The rotor system uses its own minimum elevation setting (ROTOR_MIN_ELEVATION in .env, default 5.0 degrees). The pass prediction filter and the rotor elevation gate are independent — you might predict a pass at 8 degrees elevation but have your rotor configured to refuse targets below 10 degrees.

Planning observation windows

For satellite operations, the key factors in choosing which pass to use:

1. Maximum elevation — higher is better for signal quality. Passes above 45 degrees are worth planning around. Passes above 70 degrees are the best you will get for most LEO satellites.

2. Duration — longer passes give you more operating time. A high-elevation ISS pass can last 9-10 minutes; a low pass might only be 2-3 minutes.

3. AOS/LOS azimuth — tells you which direction the satellite enters and exits your sky. Important if you have obstructions in certain directions.

4. Time of day — for visual observation, you need the satellite to be sunlit while your sky is dark. The is_visible flag in the API response indicates this when available.

To scan a longer window:

# Look ahead a full week
curl "https://your-domain/api/passes?sat=25544&hours=168&min_el=10"

How the math works

Craft uses Skyfield to propagate satellite orbits. Under the hood, the find_events() method on Skyfield’s EarthSatellite class does the work:

1. Load the satellite’s TLE and construct an SGP4 propagator
2. Set the observer position using WGS84 coordinates from your configured location
3. Step forward in time from now to the prediction horizon
4. Identify rise (event 0), culmination (event 1), and set (event 2) events relative to the minimum altitude
5. Compute topocentric azimuth and altitude at each event time

This runs server-side as a single Skyfield call. A 24-hour prediction for one satellite typically completes in under 100ms.