spacetrack

Interface to Space-Track.org for retrieving Two-Line Element (TLE) data.

This module provides access to Space-Track.org, the official source for orbital element sets for Earth-orbiting objects tracked by the U.S. Space Surveillance Network.

Classes

SpaceTrackQuery([username, password, ...])	Handles queries to the Space-Track.org API for retrieving TLEs and other space data.
OMMUtils()	Stateless utility class for working with OMM (Orbit Mean-Elements Message) records in dictionary form.

class SpaceTrackQuery(username: str | None = None, password: str | None = None, spacetrack_url: str = 'https://www.space-track.org', tle_data_folder: str = '/home/docs/.tudat/resource/tle_data', timeout: int = 60)

Bases: object

Handles queries to the Space-Track.org API for retrieving TLEs and other space data. Manages authentication, session persistence, and local caching to minimise API usage.

For working with the retrieved OMM records, see OMMUtils.

__init__(username: str | None = None, password: str | None = None, spacetrack_url: str = 'https://www.space-track.org', tle_data_folder: str = '/home/docs/.tudat/resource/tle_data', timeout: int = 60) → None

Parameters:

• username (str | None, optional) – Space-Track.org username. Prompted interactively if not provided.

• password (str | None, optional) – Space-Track.org password. Prompted interactively if not provided.

• spacetrack_url (str, optional) – Base URL. Defaults to 'https://www.space-track.org'.

• tle_data_folder (str, optional) – Directory for locally cached TLE files.

descending_epoch(N: int | None = None, update_existing: bool = False, filename: str | None = None) → list | None

Retrieves GP data ordered by epoch (most recent first).

Parameters:

• N (int | None) – Optional result limit.

• update_existing (bool) – True → merge. False → overwrite.

• filename (str | None) – Optional filename override.

Returns:

List of OMM records or None if the request failed.

Return type:

list | None

filtered_by_oe_dict(filter_oe_dict: dict[str, tuple[float | None, float | None]], limit: int = 100, output_file: str = 'filtered_results.json', update_existing: bool = False) → list | None

Retrieves payloads filtered by orbital element bounds.

Parameters:

• filter_oe_dict (dict) – Mapping of orbital element names to (min, max) bound tuples. Either bound may be None for a one-sided filter.

• limit (int) – Maximum number of results.

• output_file (str) – Cache filename.

• update_existing (bool) – True → merge. False → overwrite.

Returns:

List of OMM records or None if the request failed.

Return type:

list | None

get_tles_by_norad_ids(norad_ids: int | list[int], history: bool = False, orderby: str = 'epoch desc', limit_per_object: int = 1, update_existing: bool = False, filename: str | None = None) → list | None

Retrieves TLEs for one or more specific NORAD IDs.

Parameters:

• norad_ids (int | list[int]) – One or more NORAD IDs.

• history (bool) – If True, queries gp_history for historical records.

• orderby (str) – API ordering string.

• limit_per_object (int) – Maximum records per object.

• update_existing (bool) – True → merge. False → overwrite.

• filename (str | None) – Force a specific cache filename.

Returns:

List of OMM records or None if the request failed.

Return type:

list | None

get_tles_for_date_range(norad_id: int | str, start_date: str, end_date: str, override_last_api_hit: bool = False) → list[dict] | None

Retrieves TLEs for a single satellite over a date range.

Respects a 1.5-hour API cooldown to avoid hammering the server when data is absent (e.g. the satellite had not yet launched).

Parameters:

• norad_id (int | str) – NORAD catalogue ID.

• start_date (str) – Start of range, "YYYY-MM-DD".

• end_date (str) – End of range, "YYYY-MM-DD".

• override_last_api_hit (bool) – If True, bypass the cooldown and force an API call.

Returns:

OMM records within the requested window.

Return type:

list[dict] | None

latest_on_orbit(update_existing: bool = False, filename: str | None = None) → list | None

Retrieves the newest propagable element set for all on-orbit payloads.

Parameters:

• update_existing (bool) – True → merge into existing file. False → overwrite.

• filename (str | None) – Optional filename override. Defaults to 'latest_on_orbit.json'.

Returns:

List of OMM records or None if the request failed.

Return type:

list | None

logout() → None

Logs out and closes the session. Safe to call multiple times.

query_from_query_builder_url(query: str, output_file: str = 'custom_query.json', update_existing: bool = False) → list | None

Executes a user-provided Space-Track query URL or query path.

The input may be: - a full URL copied from the Space-Track ‘Query Builder’ - only the query path starting from ‘basicspacedata/query/…’

Parameters:

• query (str) – Full Space-Track API URL or query path.

• output_file (str) – Local cache filename.

• update_existing (bool) – True → merge with existing cache. False → overwrite.

Returns:

JSON records returned by the API.

Return type:

list | None

class OMMUtils

Bases: object

Stateless utility class for working with OMM (Orbit Mean-Elements Message) records in dictionary form.

This class has no dependency on Space-Track.org or any particular data source — it operates on plain OMM dicts regardless of where they came from. All methods are static; instantiation is not required.

static clean_file(filepath: str) → None

Removes duplicate TLE entries from a cache file in-place.

Supports both legacy (plain list) and current (dict with metadata) formats. When two records share the same EPOCH, the one with the later CREATION_DATE is kept.

Parameters:

filepath (str) – Absolute path to the cache file.

Return type:

None

static get_tles(json_data: list[dict] | dict) → defaultdict[str, list[tuple[str, str]]]

Extracts TLE line pairs from a list of OMM records.

Parameters:

json_data (list[dict] | dict) – One or more OMM records containing TLE_LINE1 and TLE_LINE2.

Returns:

Mapping of NORAD ID (str) → (TLE line 1, TLE line 2).

Return type:

dict[str, tuple[str, str]]

static get_tudat_keplerian_element_set(omm: dict) → tuple[float, float, float, float, float, float]

Extracts and converts Keplerian elements from a single OMM record into SI units suitable for Tudat.

Parameters:

omm (dict) – A single OMM record (km and degrees, as returned by Space-Track or any compliant source).

Returns:

(a, e, i, omega, RAAN, true_anomaly) where distances are in metres and angles are in radians.

Return type:

tuple[float, float, float, float, float, float]

Raises:

• TypeError – If omm is a list rather than a single dict.

• ValueError – If omm is empty or falsy.

static save_batch_to_individual_files(json_data: list[dict], output_folder: str) → list[str] | None

Splits a batch list of OMM records into one JSON file per NORAD ID.

Parameters:

• json_data (list[dict]) – Batch OMM records, each containing a NORAD_CAT_ID field.

• output_folder (str) – Directory in which to write the per-satellite files.

Returns:

List of created filenames (basenames only), or None if no data.

Return type:

list[str] | None

static tle_to_TleEphemeris_object(tle_line_1: str, tle_line_2: str) → Tle

Converts a TLE line pair into a Tudat TleEphemeris object.

Parameters:

• tle_line_1 (str) – First line of the TLE.

• tle_line_2 (str) – Second line of the TLE.

Returns:

Configured TleEphemeris object.

Return type:

environment.Tle

static tle_to_Tle_object(tle_line_1: str, tle_line_2: str) → TleEphemeris

Converts a TLE line pair into a Tudat TleEphemeris object.

Parameters:

• tle_line_1 (str) – First line of the TLE.

• tle_line_2 (str) – Second line of the TLE.

Returns:

Tle object.

Return type:

environment.Tle