Skip to content

CelesTrak Functions

Functions for accessing satellite ephemeris data from CelesTrak.

All functions are available via brahe.datasets.celestrak.<function_name>.

get_ephemeris

celestrak_get_ephemeris builtin 

celestrak_get_ephemeris(group: str) -> list[tuple[str, str, str]]

Get satellite ephemeris data from CelesTrak

Downloads and parses 3LE (three-line element) data for the specified satellite group from CelesTrak (https://celestrak.org).

Parameters:

Name Type Description Default
group str

Satellite group name (e.g., "active", "stations", "gnss", "last-30-days"). See https://celestrak.org/NORAD/elements/ for available groups.

 required

Returns:

Type Description
list[tuple[str, str, str]]

list[tuple[str, str, str]]: List of (name, line1, line2) tuples containing satellite names and TLE lines.

Raises:

Type Description
RuntimeError

If download fails or data cannot be parsed.
Example 
import brahe as bh

# Download ephemeris for ground stations
ephemeris = bh.datasets.celestrak.get_ephemeris("stations")

# Print first 5 satellites
for name, line1, line2 in ephemeris[:5]:
    print(f"Satellite: {name}")
    print(f"  Line 1: {line1[:20]}...")

get_ephemeris_as_propagators

celestrak_get_ephemeris_as_propagators builtin 

celestrak_get_ephemeris_as_propagators(group: str, step_size: float) -> list[SGPPropagator]

Get satellite ephemeris as SGP propagators from CelesTrak

Downloads and parses 3LE data from CelesTrak, then creates SGP4/SDP4 propagators for each satellite. This is a convenient way to get ready-to-use propagators.

Parameters:

Name Type Description Default
group str

Satellite group name (e.g., "active", "stations", "gnss", "last-30-days").

 required
step_size float

Default step size for propagators in seconds.

 required

Returns:

Type Description
list[SGPPropagator]

list[SGPPropagator]: List of configured SGP propagators (PySGPPropagator), one per satellite.

Raises:

Type Description
RuntimeError

If download fails or no valid propagators can be created.
Note

Satellites with invalid TLE data will be skipped with a warning printed to stderr. The function will only raise an error if NO valid propagators can be created.

Example 
import brahe as bh

# Get propagators for GNSS satellites with 60-second step size
propagators = bh.datasets.celestrak.get_ephemeris_as_propagators("gnss", 60.0)
print(f"Loaded {len(propagators)} GNSS satellites")

# Propagate first satellite
epoch = bh.Epoch.from_datetime(2024, 1, 1, 12, 0, 0, tsys="UTC")
state = propagators[0].propagate(epoch)

download_ephemeris

celestrak_download_ephemeris builtin 

celestrak_download_ephemeris(group: str, filepath: str, content_format: str, file_format: str) -> Any

Download satellite ephemeris from CelesTrak and save to file

Downloads 3LE data from CelesTrak and serializes to the specified file format. The file can contain either 2-line elements (TLE, without names) or 3-line elements (3LE, with satellite names), and can be saved as plain text, CSV, or JSON.

Parameters:

Name Type Description Default
group str

Satellite group name (e.g., "active", "stations", "gnss", "last-30-days").

 required
filepath str

Output file path. Parent directories will be created if needed.

 required
content_format str

Content format - "tle" (2-line without names) or "3le" (3-line with names).

 required
file_format str

File format - "txt" (plain text), "csv" (comma-separated), or "json" (JSON array).

 required

Raises:

Type Description
RuntimeError

If download fails, format is invalid, or file cannot be written.
Example 
import brahe as bh

# Download GNSS satellites as 3LE in JSON format
bh.datasets.celestrak.download_ephemeris("gnss", "gnss_sats.json", "3le", "json")

# Download active satellites as 2LE in plain text
bh.datasets.celestrak.download_ephemeris("active", "active.txt", "tle", "txt")

# Download stations as 3LE in CSV format
bh.datasets.celestrak.download_ephemeris("stations", "stations.csv", "3le", "csv")