Trajectories

A trajectory is a series of state vectors (position, velocity, time and covariance) related to a single object. Depending on the file format, it may contain other metadata as well.

Supported Formats

Our system supports both OEM (Orbital Ephemeris Message) and Modified ITC formats for trajectories.

If a file starts with "CCSDS_OEM_VERS", the system attempts to parse it as an OEM file. Otherwise, it attempts to parse it as a Modified ITC file.

OEM (Orbital Ephemeris Message)

OEM (Orbital Ephemeris Message) format is defined in Section 5, and Section 7.7.2, of the CCSDS spec (link)

We accept a subset of OEM-formatted trajectories, subject to the supported reference frames and time systems (below) and the general trajectory requirements.

Sample OEM File

CCSDS_OEM_VERS = 3.0
CREATION_DATE = 2023-11-06T02:08:15.481374Z
ORIGINATOR = SPACEX/USA
 
META_START
OBJECT_NAME = STARLINK-3179
OBJECT_ID = 31790
CENTER_NAME = EARTH
REF_FRAME = ITRF
TIME_SYSTEM = UTC
START_TIME = 2023-11-06T02:09:42.000000Z
STOP_TIME = 2023-11-06T02:15:42.000000Z
META_STOP
 
2023-11-06T02:09:42.000000Z -4.542752e+03 -3.316417e+03 3.877276e+03 4.819418e+00 9.779460e-02 5.717377e+00
2023-11-06T02:10:42.000000Z -4.243593e+03 -3.304426e+03 4.211322e+03 5.149116e+00 3.012760e-01 5.413318e+00
2023-11-06T02:11:42.000000Z -3.925285e+03 -3.280348e+03 4.526387e+03 5.457463e+00 5.005622e-01 5.084935e+00
2023-11-06T02:12:42.000000Z -3.589152e+03 -3.244456e+03 4.821057e+03 5.743052e+00 6.949538e-01 4.733722e+00
2023-11-06T02:13:42.000000Z -3.236600e+03 -3.197065e+03 5.094009e+03 6.004573e+00 8.837872e-01 4.361276e+00
2023-11-06T02:14:42.000000Z -2.869109e+03 -3.138526e+03 5.344019e+03 6.240812e+00 1.066436e+00 3.969275e+00
2023-11-06T02:15:42.000000Z -2.488230e+03 -3.069228e+03 5.569967e+03 6.450669e+00 1.242312e+00 3.559489e+00
 
 
COVARIANCE_START
EPOCH = 2023-11-06T02:09:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:10:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:11:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:12:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:13:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:14:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
EPOCH = 2023-11-06T02:15:42.000000Z
COV_REF_FRAME = RTN
1.000000e+00
0.000000e+00 1.000000e+02
0.000000e+00 0.000000e+00 6.400000e-01
0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 0.000000e+00 1.000000e-08
COVARIANCE_STOP

Reference Frame and Time Systems

SpaceX supports a subset of the reference frames and time systems outlined in the OEM format.

For position and velocity, we support:

• ITRF (specifically, ITRF2008)
• EME2000

Note the supported covariance reference frames diverge from the OEM standard which requires COV_REF_FRAME, if specified, to be one of RTN, RSW, TNW; however, the standard also says if COV_REF_FRAME is not provided then the covariance matrices shall be specified in the reference frame of the position and velocity. For this reason we support the following covariance reference frames:

• RTN
• ITRF
• EME2000

If COV_REF_FRAME is specified then it currently must be specified for every covariance matrix. All covariance timestamps must have a 1-to-1 mapping with state vector timestamps, so a covariance must be present for every position.

The preferred reference frame for position and velocity is ITRF as this is the native frame that the system uses during screening.

Timestamps must be in UTC in a date time string format as specified by the OEM standard. The standard for OEM files suggests GPS time is supported, but does not specify a format for this field and thus is not currently supported.

Modified ITC Format

Modified ITC format is described in the 18th Space Control Squadrons SpaceFlight Safety Handbook, p. 19.

It consists of three header lines (which can contain any information), the covariance reference frame (which must be UVW), and then blocks of 4 lines, each with 7 space-separated elements.

The the first line in each block contains a timestamp in yyyyDOYhhmmss.sss format, followed by 3 values representing position (in kilometers) and 3 values representing velocity (in kilometers per second).

The next three lines in each block contain the 21 covariance values that comprise the 6x6 lower triangular of the position and velocity covariance matrix.

Sample Modified ITC File

Arbitrary header line 1
Arbitrary header line 2
Arbitrary header line 3
UVW
2024050151742.000 -2717.6470601984 -4974.3191485700 -4003.8489578142 6.8863163410 -1.5414737334 -2.7602780986
4.8636600485e-07 -3.9604629126e-07 7.8226290555e-07 4.2441083688e-11 2.6517660097e-10 1.2714198064e-06 8.3869086144e-10
-9.1266964668e-10 -1.1434249337e-12 1.9517000894e-12 -4.7079913171e-10 4.1138462966e-10 1.5765230207e-12 -8.2452740364e-13
5.0047937509e-13 1.4246847775e-13 -4.1273571730e-14 1.7106743443e-09 -5.6529845602e-16 1.9599736772e-15 5.4193431704e-12
2024050151842.000 -2298.9370987377 -5056.0774012191 -4160.7397897232 7.0656847685 -1.1828389855 -2.4675503309
5.3668884512e-07 -4.6349648374e-07 8.9188710483e-07 2.2657306466e-11 4.1969964753e-10 1.4901772822e-06 9.3834041889e-10
-1.0554116634e-09 -1.4669001660e-12 2.1644646970e-12 -5.2134920301e-10 4.7989466356e-10 1.9467875434e-12 -9.2510091658e-13
5.5115563161e-13 -6.2106982707e-14 3.6103206656e-13 1.9303401098e-09 -1.2228009283e-15 2.5324132092e-15 5.1873702211e-12
2024050151942.000 -1870.3713992359 -5116.1597668306 -4299.7439511044 7.2147314742 -0.8192017657 -2.1642714468
5.9006079559e-07 -5.3882512561e-07 1.0195567578e-06 -1.3771040498e-11 6.3733209461e-10 1.7334464112e-06 1.0452685485e-09
-1.2166219092e-09 -1.8938654797e-12 2.3930449422e-12 -5.7506522394e-10 5.5642533914e-10 2.3795659970e-12 -1.0332529542e-12
6.0512086419e-13 -2.9804491596e-13 8.4437284811e-13 2.1186487133e-09 -1.9788406146e-15 3.1034656668e-15 4.9262055184e-12
2024050152042.000 -1433.7884241893 -5154.3126003016 -4420.2672971496 7.3328314432 -0.4521145181 -1.8517422544
6.4629918545e-07 -6.2231422941e-07 1.1673052992e-06 -6.9880168142e-11 9.2829929550e-10 1.9972680301e-06 1.1594136677e-09
-1.3978410559e-09 -2.4368514208e-12 2.6385236017e-12 -6.3176770168e-10 6.4127556470e-10 2.8710610744e-12 -1.1489225028e-12
6.6220600395e-13 -5.6414853767e-13 1.4047888592e-12 2.2723791834e-09 -2.8209246194e-15 3.6607115289e-15 4.6405757642e-12
2024050152142.000 -991.0605167036 -5170.3758219631 -4521.7947711535 7.4194907986 -0.0831429500 -1.5313016964
7.0518100260e-07 -7.1418173349e-07 1.3372285671e-06 -1.4882993649e-10 1.3018125275e-09 2.2773278566e-06 1.2806715117e-09
-1.6006203035e-09 -3.1070484611e-12 2.9019859455e-12 -6.9123111871e-10 7.3466570109e-10 3.4158648671e-12 -1.2719836762e-12
7.2218468549e-13 -8.5898387215e-13 2.0360902508e-12 2.3888998991e-09 -3.7334432682e-15 4.1915570184e-15 4.3356265560e-12
2024050152242.000 -544.0856347396 -5164.2835175237 -4603.8926704131 7.4743487591 0.2861406689 -1.2043205866
7.6644312550e-07 -8.1456800326e-07 1.5314682612e-06 -2.5366343254e-10 1.7657644294e-09 2.5690345067e-06 1.4088817061e-09
-1.8265087523e-09 -3.9126280543e-12 3.1845030192e-12 -7.5318689788e-10 8.3673660071e-10 4.0067533860e-12 -1.4022545288e-12
7.8478607542e-13 -1.1796772309e-12 2.7294684753e-12 2.4662168584e-09 -4.6970053365e-15 4.6842571860e-15 4.0168296254e-12
2024050152342.000 -94.7793264969 -5136.0641534569 -4666.2103603739 7.4971784041 0.6541639374 -0.8721961963
8.2978665389e-07 -9.2352896570e-07 1.7521907912e-06 -3.8718873889e-10 2.3263994870e-09 2.8675972585e-06 1.5438265252e-09
-2.0770408763e-09 -4.8584806577e-12 3.4871261888e-12 -8.1732733532e-10 9.4753916942e-10 4.6349705452e-12 -1.5394908176e-12
8.4969679543e-13 -1.5220529319e-12 3.4736021911e-12 2.5030064375e-09 -5.6890352084e-15 5.1279537308e-15 3.6898907529e-12

Reference Frame and Time Systems

Per the Modified ITC specification, position and velocity must be provided in the EME2000 reference frame, and covariance must be in the UVW (a.k.a RTN) reference frame. All timestamps must be in UTC.

Trajectory Requirements

Structure

In order to efficiently screen the catalog, we enforce the following constraints on trajectory files:

• We recommend submitting your trajectory file with covariance although it is not required. (See Note below.)
• Trajectory files must have at least some state vectors in the future
• Trajectory files must span less than 7 days
• Trajectory files must have at least 6 data points
• Trajectory files must span a minimum 42 seconds
• Trajectory files must be in a supported reference frame and time system

If an operator submits a trajectory file that violates any of these requirements, they will receive an HTTP 400 (Bad Request) response with a helpful error message. Covariance Note: If covariance matrices are provided then every state vector must have an associated positive semi-definite covariance matrix. If no covariance is provided then Collision Probability will not be generated for conjunctions against this trajectory and the CDM file will have a NULL value for the COLLISION_PROBABILITY field (This diverges from the CDM CCSDS standard).

Trajectory Submission Types

The POST /api/v1/trajectory endpoint requires that an operator submits trajectories with an upload_type parameter, which is one of three options, described below:

Definitive trajectories indicate the trajectory a satellite is intended to fly. It is shared with all the users of the system, and the screening system's catalog assumes that the most-recently-submitted definitive trajectory is the best estimate for where an object is going to be.

Hypothetical trajectories provide a mechanism for operators to do one-off screening of maneuvers without updating an object's definitive trajectory or confusing other operators. They aren't inserted into the catalog for future trajectory submissions to screen against, and they (and their results) are only visible to the submitting operator.

Candidate trajectories provide a hybrid approach to save operators an API call; they are screened as if they are hypothetical trajectories, but if the system determines they are "safe" (according to a risk tolerance supplied by the operator), they will be converted to a "definitive" trajectory.

To summarize:

Upload Type	Use Case	Catalog Semantics	Permissions
definitive	A trajectory that an operator is planning to fly.	Inserted into the catalog, replacing the previously-uploaded definitive trajectory for the object if it exists.	Trajectory and associated events / CDMs are viewable by all users
hypothetical	A trajectory that an operator is considering flying, but would like to screen first.	Screened once, but not inserted into the catalog.	Trajectory and associated CDMs only viewable by submitting operator. No events are created.
candidate	A trajectory that an operator is considering flying, and if the system determines it is "safe" (see below), the system should "lock it in" as a definitive trajectory.	Screened once, and converted to either definitive or hypothetical on the next screening cycle based on safety criteria.	Trajectory and CDMs are private, unless the trajectory is converted to a definitive trajectory.

Trajectory Screened Status

Each trajectory has an associated status, which starts as NotScreened. Success or intermediate errors can result in the following statuses:

Status	Meaning
Screened	Trajectory successfully processed.
NotScreened	Not yet processed (default).
CandidateToDefinitive	Trajectory upgraded from a candidate to a definitive type. Only visible for a single cycle when a trajectory is converted.
TrajectoryInvalid	Trajectory file was invalid.
TrajectoryTypeResolutionFailed	Trajectory type could not be resolved to one of the above types.
Superseded	Trajectory was not screened because there was a newer definitive trajectory for that object in the same screening cycle.

Superseded Trajectories

If there are multiple definitive trajectories for the same object downloaded in a single screening cycle, only the newest (by upload time) will be screened. New definitive trajectories for an object will also replace older definitive trajectories for the same object from previous cycles.

Using Candidate Trajectories

The POST /api/v1/trajectory endpoint has an optional auto_relinquish_pc_threhold parameter (defaults to 0.0). When specified with a candidate trajectory, it expresses the operator's risk tolerance for "locking in" a trajectory.

If all CDMs generated by the screening of a candidate trajectory have a collision probability less than or equal to auto_relinquish_pc_threshold, then the trajectory is upgraded to a definitive trajectory on the next screening cycle.

The name of the field comes from a second semantic meaning of the field, which is relevant when an object has pre-existing conjunction events. To learn more, read about coordinating on conjunction events.

SpaceX Trajectory Uploads

Starlink uploads ephemerides for every satellite in its constellation to the production space-safety.starlink.com roughly every 30 minutes, with a 24 hour time horizon, subject to change due to operational considerations.