Tracking Satellites

Craft tracks over 22,000 satellites in its catalog, from the ISS to recently launched CubeSats. This guide covers how to find a satellite, read its orbital data, and follow it across the sky in real time.

Finding a satellite

You have two ways to locate a satellite: the command palette and the search bar.

Command palette

Press Ctrl+K (or Cmd+K on macOS) to open the command palette. Start typing a satellite name or NORAD catalog number and results appear as you type.

The command palette searches across all object types — satellites, planets, stars, DSOs, comets, and radio frequencies. To narrow results to satellites only, prefix your query with /sat:

/sat ISS
/sat 25544
/sat starlink

API search

You can also search programmatically:

# Search by name
curl "https://your-domain/api/search?q=ISS"

# Filter to satellites only
curl "https://your-domain/api/search?q=starlink&types=satellite"

# Look up a specific NORAD ID
curl "https://your-domain/api/satellites/25544"

Reading the satellite detail view

When you select a satellite, the detail view shows:

• Name and NORAD ID — the catalog designation and five-digit identifier assigned by USSPACECOM
• International designator — the launch year, launch number, and piece designator (e.g., 1998-067A for the ISS)
• TLE epoch — when the orbital elements were last updated
• Orbit type — LEO, MEO, GEO, HEO, or other classifications
• Object type — payload, rocket body, or debris
• Groups — CelesTrak group memberships (e.g., stations, starlink, amateur)
• Current position — live altitude, azimuth, distance, and RA/Dec coordinates

Real-time tracking on the 3D globe

Click “Track” on any satellite to follow it on the CesiumJS globe. The globe view shows:

• The satellite’s current position as a marker
• Its ground track (the path its sub-satellite point traces on the Earth’s surface)
• Your observer location
• The satellite’s footprint (the area on Earth from which it is visible)

The position updates at 60fps for smooth animation. This is possible because of a deliberate split between server-side and client-side computation.

Server-side vs. client-side propagation

Craft uses two independent SGP4 implementations that serve different purposes:

Server (Skyfield)

The FastAPI backend uses Skyfield for all authoritative position calculations. Skyfield applies the full SGP4/SDP4 propagation model along with proper coordinate transformations, Earth orientation parameters, and nutation corrections.

Server-side positions are used for:

• Pass predictions (rise/culmination/set events)
• Rotor pointing commands
• Altitude/azimuth readouts in the detail view
• API responses and MCP tool results

The server sends position updates over WebSocket at 1 Hz via /ws/tracking/{target_type}/{target_id}.

Client (satellite.js)

The Astro frontend uses satellite.js to propagate TLE data directly in the browser. This runs in the animation loop at up to 60fps, producing the smooth globe animation you see when tracking.

Client-side propagation handles:

• Globe marker animation between server updates
• Ground track rendering
• Footprint visualization

The client receives authoritative positions from the server at 1 Hz and uses its own SGP4 output for interpolation between those updates. This gives you smooth visuals without requiring 60 WebSocket messages per second.

Tip

Both implementations use the same TLE data. The difference is that Skyfield applies additional corrections (precession, nutation, polar motion) that make its output more accurate for operational use like rotor pointing. For visual tracking on the globe, the satellite.js output is more than adequate.

TLE freshness and auto-updates

Two-Line Elements (TLEs) degrade over time as atmospheric drag and other perturbations cause the actual orbit to diverge from the predicted one. A TLE that is a few days old might be off by a few kilometers; one that is weeks old can be off by hundreds.

Craft handles this automatically:

• Background scheduler — the API fetches updated TLEs from CelesTrak on a regular interval
• Epoch age display — the satellite detail view shows how old the current TLE is
• Staleness indicators — satellites with TLEs older than 7 days are flagged

You do not need to manually refresh TLEs. If you need to force an update for a specific satellite, you can trigger a fetch through the API:

curl -X POST "https://your-domain/api/satellites/refresh"

CelesTrak as the TLE source

Craft sources its TLE data from CelesTrak, which redistributes USSPACECOM data. The catalog covers active payloads, rocket bodies, and tracked debris. If you have Space-Track credentials, Craft can also pull directly from Space-Track for supplementary data — set SPACETRACK_USER and SPACETRACK_PASS in your .env.