CelesTrak Functions¶

Functions for accessing satellite ephemeris data from CelesTrak.

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

download_tles¶

celestrak_download_tles `builtin` ¶

celestrak_download_tles(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_tles("gnss", "gnss_sats.json", "3le", "json")

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

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

get_tle_by_id¶

celestrak_get_tle_by_id `builtin` ¶

celestrak_get_tle_by_id(norad_id: int, group: str = None) -> tuple[str, str, str]

Get TLE data for a specific satellite by NORAD catalog number

Downloads 3LE data from CelesTrak for a single satellite identified by its NORAD catalog number. Uses cached data if available and less than 6 hours old.

Parameters:

Name	Type	Description	Default
`norad_id`	`int`	NORAD catalog number (1-9 digits).	required
`group`	`str`	Satellite group for fallback search if direct ID lookup fails. Available groups can be found at https://celestrak.org/NORAD/elements/	`None`

Returns:

Type	Description
`tuple[str, str, str]`	tuple[str, str, str]: Tuple of (name, line1, line2) containing satellite name and TLE lines.

Raises:

Type	Description
`RuntimeError`	If download fails or satellite not found.

Example

import brahe as bh

# Get ISS TLE by NORAD ID (25544)
name, line1, line2 = bh.datasets.celestrak.get_tle_by_id(25544)
print(f"Satellite: {name}")
print(f"Line 1: {line1}")
print(f"Line 2: {line2}")

# With group fallback
tle = bh.datasets.celestrak.get_tle_by_id(25544, group="stations")

Note

You can find which group contains a specific NORAD ID at: https://celestrak.org/NORAD/elements/master-gp-index.php

Data is cached for 6 hours to reduce server load and improve performance.

get_tle_by_id_as_propagator¶

celestrak_get_tle_by_id_as_propagator `builtin` ¶

celestrak_get_tle_by_id_as_propagator(norad_id: int, step_size: float, group: str = None) -> SGPPropagator

Get TLE data for a specific satellite as an SGP propagator

Downloads TLE data from CelesTrak for a single satellite and creates an SGP4/SDP4 propagator. Uses cached data if available and less than 6 hours old.

Parameters:

Name	Type	Description	Default
`norad_id`	`int`	NORAD catalog number (1-9 digits).	required
`step_size`	`float`	Default step size for propagator in seconds.	required
`group`	`str`	Satellite group for fallback search if direct ID lookup fails.	`None`

Returns:

Name	Type	Description
`SGPPropagator`	`SGPPropagator`	Configured SGP propagator (PySGPPropagator) ready to use.

Raises:

Type	Description
`RuntimeError`	If download fails, satellite not found, or TLE is invalid.

Example

import brahe as bh

# Get ISS as propagator with 60-second step size
propagator = bh.datasets.celestrak.get_tle_by_id_as_propagator(25544, 60.0)

# Propagate to current epoch
epoch = bh.Epoch.now()
state = propagator.propagate(epoch)
print(f"ISS position: {state[:3]}")

# With group fallback
prop = bh.datasets.celestrak.get_tle_by_id_as_propagator(
    25544, 60.0, group="stations"
)

Note

You can find which group contains a specific NORAD ID at: https://celestrak.org/NORAD/elements/master-gp-index.php

Data is cached for 6 hours to reduce server load and improve performance.

get_tle_by_name¶

celestrak_get_tle_by_name `builtin` ¶

celestrak_get_tle_by_name(name: str, group: str = None) -> tuple[str, str, str]

Get TLE data for a specific satellite by name

Searches for a satellite by name using a cascading search strategy: 1. If a group is provided, search within that group first 2. Fall back to searching the "active" group 3. Fall back to using CelesTrak's NAME API

Uses cached data if available and less than 6 hours old.

Parameters:

Name	Type	Description	Default
`name`	`str`	Satellite name (case-insensitive, partial matches supported).	required
`group`	`str`	Satellite group to search first. Available groups can be found at https://celestrak.org/NORAD/elements/	`None`

Returns:

Type	Description
`tuple[str, str, str]`	tuple[str, str, str]: Tuple of (name, line1, line2) containing satellite name and TLE lines.

Raises:

Type	Description
`RuntimeError`	If download fails or satellite not found.

Example

import brahe as bh

# Search for ISS with group hint
name, line1, line2 = bh.datasets.celestrak.get_tle_by_name("ISS", group="stations")
print(f"Found: {name}")

# Search without group (uses cascading search)
tle = bh.datasets.celestrak.get_tle_by_name("STARLINK-1234")

Note

Name matching is case-insensitive
Partial names are supported (e.g., "ISS" will match "ISS (ZARYA)")
If multiple satellites match, returns the first match
Search order: specified group → "active" → NAME API
Data is cached for 6 hours to reduce server load

get_tle_by_name_as_propagator¶

celestrak_get_tle_by_name_as_propagator `builtin` ¶

celestrak_get_tle_by_name_as_propagator(name: str, step_size: float, group: str = None) -> SGPPropagator

Get TLE data for a specific satellite by name as an SGP propagator

Searches for a satellite by name and creates an SGP4/SDP4 propagator. Uses cascading search strategy (specified group → active → NAME API). Uses cached data if available and less than 6 hours old.

Parameters:

Name	Type	Description	Default
`name`	`str`	Satellite name (case-insensitive, partial matches supported).	required
`step_size`	`float`	Default step size for propagator in seconds.	required
`group`	`str`	Satellite group to search first.	`None`

Returns:

Name	Type	Description
`SGPPropagator`	`SGPPropagator`	Configured SGP propagator (PySGPPropagator) ready to use.

Raises:

Type	Description
`RuntimeError`	If download fails, satellite not found, or TLE is invalid.

Example

import brahe as bh

# Get ISS as propagator with 60-second step size
propagator = bh.datasets.celestrak.get_tle_by_name_as_propagator("ISS", 60.0, group="stations")

# Propagate to current epoch
epoch = bh.Epoch.now()
state = propagator.propagate(epoch)
print(f"Position: {state[:3]}")

Note

Data is cached for 6 hours to reduce server load and improve performance.

get_tles¶

celestrak_get_tles `builtin` ¶

celestrak_get_tles(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_tles("stations")

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

get_tles_as_propagators¶

celestrak_get_tles_as_propagators `builtin` ¶

celestrak_get_tles_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_tles_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)

CelesTrak Functions¶

download_tles¶

celestrak_download_tles builtin ¶

get_tle_by_id¶

celestrak_get_tle_by_id builtin ¶

get_tle_by_id_as_propagator¶

celestrak_get_tle_by_id_as_propagator builtin ¶

get_tle_by_name¶

celestrak_get_tle_by_name builtin ¶

get_tle_by_name_as_propagator¶

celestrak_get_tle_by_name_as_propagator builtin ¶

get_tles¶

celestrak_get_tles builtin ¶

get_tles_as_propagators¶

celestrak_get_tles_as_propagators builtin ¶

celestrak_download_tles `builtin` ¶

celestrak_get_tle_by_id `builtin` ¶

celestrak_get_tle_by_id_as_propagator `builtin` ¶

celestrak_get_tle_by_name `builtin` ¶

celestrak_get_tle_by_name_as_propagator `builtin` ¶

celestrak_get_tles `builtin` ¶

celestrak_get_tles_as_propagators `builtin` ¶