astra.spacetrack module

ASTRA Core Space-Track.org Data Ingestion Module.

Provides authenticated access to the 18th Space Defense Squadron’s Space-Track.org catalog — the most authoritative and complete source of orbital element data, covering over 27,000 tracked objects.

Authentication:

Space-Track requires a free account. Credentials are read from environment variables to keep them out of source code:

Windows:

setx SPACETRACK_USER your@email.com
setx SPACETRACK_PASS yourpassword

Linux / macOS:

export SPACETRACK_USER=your@email.com
export SPACETRACK_PASS=yourpassword

Then restart your Python session. If the environment variables are not set, AstraError is raised with exact instructions on how to fix it.

Supported Formats:

• format="json" (default, recommended): Returns list[SatelliteOMM] with full physical metadata (mass, RCS, ballistic coefficient).

• format="tle": Returns list[SatelliteTLE] for legacy workflows.

Example:

import astra

# Fetch Starlink constellation in OMM format (recommended)
starlinks = astra.fetch_spacetrack_group("starlink")

# Use it directly in the physics pipeline
leo = astra.filter_altitude(
    [astra.make_debris_object(s) for s in starlinks], 500, 600
)

astra.spacetrack.spacetrack_logout()

Clear session cache and logout of Space-Track.

astra.spacetrack.fetch_spacetrack_group(group, format='json')

Fetch a satellite group from Space-Track.org using authenticated access.

Data formats: ✓ SatelliteOMM (format=”json”, default) ✓ SatelliteTLE (format=”tle”)

Credentials are read automatically from environment variables SPACETRACK_USER and SPACETRACK_PASS. If not set, an AstraError is raised with exact instructions on how to configure them.

Parameters:

• group – Group name string (e.g. "starlink", "gps-ops", "iridium-33-debris").

• format – "json" (default) for OMM with full physical metadata, "tle" for legacy TLE format.

Returns:

• list[SatelliteOMM] when format="json"

• list[SatelliteTLE] when format="tle"

Raises:

AstraError – If credentials are missing, authentication fails, or the network request fails.

Example:

import astra

# Fetch Starlink in OMM format (recommended — includes RCS, mass)
starlinks = astra.fetch_spacetrack_group("starlink")

# Fetch GPS constellation in legacy TLE format
gps_tles = astra.fetch_spacetrack_group("gps-ops", format="tle")

astra.spacetrack.fetch_spacetrack_active(format='json')

Fetch all active satellites from Space-Track.org using authenticated access.

Data formats: ✓ SatelliteOMM (format=”json”, default) ✓ SatelliteTLE (format=”tle”)

Credentials are read automatically from environment variables SPACETRACK_USER and SPACETRACK_PASS.

Parameters:

format – "json" (default) for OMM with full physical metadata, "tle" for legacy TLE format.

Returns:

• list[SatelliteOMM] when format="json"

• list[SatelliteTLE] when format="tle"

Raises:

AstraError – If credentials are missing or authentication fails.

Example:

import astra
catalog = astra.fetch_spacetrack_active()
print(f"Loaded {len(catalog)} active satellites from Space-Track.")

astra.spacetrack.fetch_spacetrack_satcat(norad_ids=None)

Fetch metadata from the General Perturbations Satellite Catalog (SATCAT).

The SATCAT contains object type classification, launch date, decay date, and country of origin.

Parameters:

norad_ids – Optional list of NORAD IDs to filter by. If None, fetches the entire catalog (which may be very large).

Returns:

List of dictionaries containing SATCAT metadata.