Skip to main content

Two-line element (TLE) management with a focus on downloading and operating on every TLE ever published by Space-Track

Project description

TL3

tl3 provides two things: the ability to automatically and efficiently download every two-line element (TLE) ever published by Space-Track (while staying within the API-imposed rate limit), and piping the 28 GB of resulting .txt files into a parquet file for efficient analysis using packages like duckdb or polars.

Installation

pip install tl3

The package should work wherever Polars and DuckDB (its primary dependencies) work.

Quickstart

To pull all TLEs from 1958 to the end of the previous UTC day, run:

import tl3

date_pairs = tl3.load_query_dates()
# Loads nicely-distributed dates to make each api query roughly the same size (20 MB)
tl3.save_tles(date_pairs)
# Makes queries to the Space-Track API, this takes about 5 hours for all dates
tl3.update_tle_cache()
# Pulls any dates after the above query dates were generated
tl3.build_parquet(from_scratch=True)
# Concatenates all TLE txt files into one parquet for efficient querying

This will download (while remaining within the rate limits) ~28 GB of raw TLE .txt files, and build a single parquet file out of the results.

Be considerate to Space-Track when using this package. tl3 automatically stays below the rate limit imposed by Space-Track, but do not repeatedly query all TLEs multiple times. The developer of tl3 is not responsible for any consequences resulting from its use.

The first time you import tl3, you will be prompted for your Space-Track login credentials, which are cached locally for all requests.

Querying The Database

Once the parquet file is built, you can run queries against the full dataset using duckdb. For example, you can query the NORAD catalog IDs for all polar satellites in LEO with at least one TLE produced in 2024 with:

import tl3
import duckdb

df = duckdb.sql(f"""
   SELECT DISTINCT NORAD_CAT_ID FROM {repr(tl3.DB_PATH)}
   WHERE EPOCH BETWEEN '2024-01-01' AND '2025-01-01'
   AND ABS(INC - 90) < 0.1
   AND N < 10
""").pl()

Which returns a Polars dataframe:

┌──────────────┐
│ NORAD_CAT_ID │
│ ---          │
│ u32          │
╞══════════════╡
│ 2876         │
│ 54153        │
│ 54154        │
│ 2877         │
│ 2861         │
└──────────────┘

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tl3-0.0.5.tar.gz (15.5 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page