As a service to the satellite user community, CelesTrak provides the
Space Track TLE Retriever—a tool which allows users with an
active Space Track
account to easily download Space Track data sets and use them to generate
standard CelesTrak data sets. The Space Track TLE Retriever is a
standalone Windows-based application which can be run manually, as needed, or
set up to automatically download and generate CelesTrak data sets. All
downloaded data is automatically archived for the user.
The latest version of the Space Track TLE Retriever is Version 188.8.131.52 (2018 Sep 08). You will also need
.NET Framework 3.5 Service Pack 1, if you do not already have it installed.
Information on bug fixes, known bugs, workarounds, and future enhancements can
be found in the Update History.
The Space Track TLE Retriever consists of three major parts:
All settings can be saved from the File menu for future use.
- A Processing section which allows the user to specify the processing
configuration, download Space Track data sets, and convert Space Track data
into CelesTrak data sets.
- A Space Track section which allows the user to specify their Space Track
username and password, which data files to download, and which formats to use
(two-line or three-line).
- A CelesTrak section which allows the user to specify which, if any,
CelesTrak data sets to generate.
In its simplest form, once the user has selected which Space Track data
sets to download, they need only click Download Data to check for and
download all new user-specified files. To generate CelesTrak data sets, the
user then simply clicks Process Data. All CelesTrak data sets are
quality-checked and formatted to the community-standard TLE format, as has
been the practice with all data published on CelesTrak for decades—using
the latest Space Track data. These files should then be immediately ready for
use in existing applications which currently rely on CelesTrak data sets.
- The user must have a current Space Track account to download
Space Track data. The user may request an account by going to www.space-track.org. After receiving
their Space Track account, the user must log in to their account
manually via the Space Track web site to change their password, before using
TLE Retriever for the first time.
- The user must provide a valid Space Track username and password
on the Space Track tab before the Download
Data button will be enabled.
- The user must download Space Track data before the Process
Data button will be enabled. The user must either download the Full
Catalog in the three-line format or the Full Catalog in the two-line format
along with the Satellite Situation Report.
Specific detailed information on how to use the Space Track TLE
Retriever is provided below.
To install the Space Track TLE Retriever, simply extract
all of the files into any directory. Then double-click on
TLERetriever3.exe to run.
- Save Settings: Saves all current settings, including Space
Track username and password (if "Retain username and password" is checked).
- Open My TLEs: All TLEs downloaded from Space Track are
archived in the My TLEs directory under the user's (My) Documents directory. The
program automatically determines where the (My) Documents directory is located and
creates a My TLEs directory on startup, if one does not already
exist. All Space Track data are archived under this directory by year and
then by file type. This menu selection makes it easy to open the My
TLEs directory for direct file access.
- Open User Data: Opens the directory that
contains any user-defined data sets.
- Create Basic Job: Uses the schtasks.exe
command-line interface—which is supposed to support Windows XP
Pro/Windows 2003 Server and beyond—to create a basic Windows
task, using the settings in the Auto Download section of the Processing tab. The user may wish to further edit
these settings using Task Scheduler/Scheduled Tasks.
- Exit: Exits the program. Will prompt to save changes,
if any have been made since last save.
- Web Sites
- CelesTrak: Opens the user's browser and goes to the
CelesTrak main page.
- Space Track: Opens the user's browser and goes to the
user's Space Track home page. The program will use the user's username and password, if available,
to automatically log the user into their Space Track account. It is the
user's responsibility to ensure this information is correct (the program has
no way of verifying it).
- Online Help: Opens the user's browser and goes to this
- Check for Update: Checks CelesTrak to see whether there is
a more current version of TLE Retriever available.
- About: Opens the About tab to provide
basic information about the current version of TLE Retriever. Also
includes an e-mail link to the author to provide user feedback.
- Send Debug Log: Opens the log file directory and the
user's mail client with a pre-addressed message to send debugging
information to help identify and resolve problems. Debug logs are automatically
generated any time TLE Retriever is run with "Enable debug logging" checked.
A new log is generated for each run, with a filename of the format
- Open Debug Log Directory: Opens the directory where the
TLE Retriever logs are stored.
- Auto Download: If this box is not checked, the user must
manually download and/or process the data. If this box is checked, the
program will be configured to automatically download and/or process the
selected data sets, by creating a shortcut in the user's Startup directory
and setting up TLE Retriever to run from the System Tray.
- Initial Delay: If Auto Download is checked, this is
the delay in minutes before the program begins automatically downloading and
processing data. The time is measured from when the application is first
run. This value can only be changed if Auto Download is checked and
when it is changed, the countdown timer will be reset to the current value,
for use on the next startup.
- Auto Download Frequency (per day): If Auto Download
is checked, the program will automatically check for new data and/or process
it one, two, three, or four times a day. Remember, the Space Track data
files are currently only updated twice each day.
- Enable debug logging: To support finding the cause of
program difficulties, the user may check this box to enable debug logging.
The program must be restarted before logging can begin. Each time the
program is restarted, the log will be reinitialized. If you experience
difficulties, please follow this procedure and send me the resulting
yyyy-MM-dd-hhmm-debug.log file for problem resolution.
- Stop on errors: Uncheck this box to turn off the warning
messages produced when TLE Retriever runs automatically. This choice
will prevent the program from stopping (e.g., if the Internet connection is
temporarily unavailable) when an automatic process is running unattended
(the program will simply reset and attempt to run again at the next
scheduled time). Please note that if this box is unchecked, it is the user's
responsibility to ensure the program is running properly, since no error
messages will be produced. Otherwise, it is possible for the program to run
indefinitely without ever doing anything.
- Download Data: Clicking this button will automatically log
the user in to their Space Track account and begin downloading the selected
data files (as indicated on the Space Track tab).
If the Space Track username and password fields are blank, the user will
receive a warning and be taken to the Space Track tab
to enter their credentials. All files are archived in the My TLEs directory
under (My) Documents, organized by year and file type. The user can
access the My TLEs directory from the File menu.
- Process Data: Clicking this button will use the latest
Full Catalog and SSR (if the Full Catalog is in
two-line format) to build standard CelesTrak data sets (as defined on the CelesTrak tab). If these files have not yet been downloaded
or are over 30 days old, the user will receive a warning and be taken to the
Space Track tab to select the appropriate files
for downloading. For each data set, the program checks for the appropriate
data set definition file on CelesTrak to ensure the most up-to-date
definition. These files consist only of the Catalog Number and CelesTrak
Common Name (which can be different than that used by Space Track, to meet a
specific user group's preferences). A sample for the International Space
Station data set might look like:
The CelesTrak Common Name may be left blank to allow for using the Space
Track Common Name. All CelesTrak data sets are stored in the
CelesTrak directory under My TLEs. Query files are stored
locally each time CelesTrak is accessed. If these files are available
locally, it is possible to generate CelesTrak data sets without Internet
connectivity (assuming Space Track data was previously downloaded).
Space Track Tab
- Space Track User Information
- Username: Space Track–provided
- Password: Space Track–provided password.
- Retain username and password: Check this box to save your
Space Track account information for future use.
- Space Track Data Sets
- TLE Data Format: Allows the user to specify whether they
want to download two-line or three-line bulk data files from Space
- Current Catalog Files: Allows the user to specify which,
if any, of the Space Track bulk catalog files to download.
NOTE: The Full Catalog data file must be downloaded
(two-line or three line format) to generate CelesTrak data sets.
- Complete Daily Data: Space Track provides complete
daily data files (in two-line format only) for each of the past seven days
(which a slight lag). Select Yes to check for, download, and archive
- Satellite Situation Report (SSR): Select Yes to
download Satellite Situation Report data. This file contains
information, such as satellite common name, international designator,
source, launch/decay dates, and basic orbital information.
NOTE: This file must be downloaded to generate CelesTrak data
sets if the Full Catalog is downloaded in two-line format.
- CelesTrak Data Sets: All of the standard CelesTrak data sets
available in the Current Data
section of CelesTrak can be selected in this section. When the Process
Data button is clicked, the data sets are generated from the latest Space
Track data and stored in the CelesTrak directory under My TLEs.
The data set definition files will be maintained current via CelesTrak. In
addition to the standard choices, there is also a choice to generate a
CelesTrak standard data set for the entire on-orbit catalog (Complete
Catalog) using Space Track common names.
- CelesTrak File Extension: Users can choose to generate
CelesTrak data sets with either .txt or .tle file extensions.
The About tab contains basic information on the current version of TLE
Retriever, the specific version of the Windows operating system being used,
and the CPU being used. This information, along with screen resolution, is
included in the debug logs for diagnostic purposes. There is also a link to
launch the user's mail client to send feedback.
Status for the program will be shown in the status bar at the bottom of the
application. Status includes showing when the program is accessing Space Track
or downloading or processing files. It also includes warning messages which
indicate when data files necessary for processing are not available. These
status messages should also indicate the status of the program should an
unexpected error occur and are included in the debug log when "Enable debug
logging" is checked on the Processing tab.
User-Defined Data Sets
Users may create as many data sets as desired by creating files of the form
[fname].query and placing them in the My TLEs\User folder. Each .query
file should contain a line for each object which consists of the NORAD Catalog
Number followed immediately by the common name (please be sure that each line
ends with a carriage return and that there are no blank lines at the end of
the file). If only the NORAD Catalog Number is provided, the program will use
the Space Track Common Name. Any objects which are not found in the current
catalog will be omitted. Each [fname].query file will produce an [fname].txt
or .tle file in the My TLEs\User folder.
Users may run TLE Retriever on an as-needed basis by running the
program with the -auto command-line option. That is:
Doing so, the program will begin executing five seconds after loading,
attempting to download the Full Catalog along with any other
user-specified Space Track data files, and then generating the user-specified
CelesTrak data sets, if any. The user should ensure that the Space Track
username and password information have been entered previously, that Retain
username and password is checked, and that the settings have been saved
prior to executing via this method. The program will terminate after all
processes have been completed. This should allow users to schedule TLE
Retriever to run as required in support of other software applications.
Users may schedule TLE Retriever using the command-line option via
Windows Task Scheduler/Scheduled Tasks.
VBScript Post Processing
Several users have expressed a need to be able to perform additional
processing in support of existing software applications which may expect data
in specific locations or require some other form of post processing. TLE
Retriever checks for the existence of the file post.vbs in the
same directory as the program, whenever it completes Process Data. The
program also writes a file named newdata.log, which contains the full
path name of any Space Track data downloaded the last time Download
Data is run. Users may create their own post.vbs file to handle
additional post-processing needs (a sample is included with the program for
illustration purposes, just to show that it is running). CelesTrak will
provide links to scripts developed by software developers to help them tailor
their applications for their users.
Combined with the command-line option described above, these features will
allow users to easily configure TLE Retriever to run on a scheduled
basis (e.g., using Windows Task Scheduler/Scheduled Tasks to
automatically download Space Track data sets, generate CelesTrak data sets,
send e-mail notifications, and/or then prepare those files for use with their
existing satellite tracking applications.
The program automatically saves the position of the form and information on
the latest Full Catalog and SSR on shutdown. It will also query
the user to save other settings if the form has been changed since the last
time these settings were saved.
Frequently Asked Questions (FAQs)
- Can I specify a data directory other than My TLEs?
- The choice of the My TLEs folder was made for three reasons:
Why do I get the error message Unable to create directory C:\My
Documents\My TLEs\ 200\\?
This problem results from the Space Track requirement that you change your
password on the first login to their site. When you first receive your Space
Track username and password, you must first log in to Space Track and change your password.
You may then use your Space Track username and new password to run TLE
- It was hoped that by defining a standard data location, directory
structure, and file formats that this would make it easier for software
developers to know where to check for and find TLE data on any user's
system. This choice is particularly important due to the restrictions placed
on redistribution of Space Track data which will prevent future applications
from providing their own data.
- With the data in a location under (My) Documents, it would be easy
for the user—and many other existing Windows applications—to
locate it quickly.
- Because of the restrictions on redistribution of Space Track data, I
felt the data needed to be saved in a location that was user-specific. In a
secure configuration, data in the My TLEs folder would not be visible
to other users of the same machine. As a result, there could be no
suggestion that TLE Retriever was designed to circumvent current US
public law in any way. Allowing the user to specify the location would
permit the selection of locations which could easily be shared with other
users. I chose this limitation to ensure the availability of TLE
Retriever to CelesTrak users would not be jeopardized.