Providing Custom Ephemeris Data
Warning
The ephemeris API is currently in a Preview state
Access to the Ephemeris API is provided only on an as-needed basis. Customers requiring the ability to upload custom ephemeris data should contact aws-groundstation@amazon.com.
Overview
The Ephemeris API allows custom ephemerides to be uploaded to AWS Ground Station for use with a satellite. These ephemerides override the default ephemerides from Space Track (see: Default Ephemeris Data).
Uploading customer ephemerides can improve the quality of tracking, handle early operations where no Space Track ephemerides are available to AWS Ground Station, and to account for maneuvers.
Creating a custom Ephemeris
A custom ephemeris can be created using the CreateEphemeris action in the AWS Ground Station
API. This action will upload an ephemeris using data either in the request body or from a specified S3 bucket.
It is important to note that uploading an ephemeris sets the ephemeris to VALIDATING and starts an asynchronous
workflow that will validate and generate potential contacts from your ephemeris. Only once an ephemeris has passed
this workflow and become ENABLED will it be used for contacts. You should poll DescribeEphemeris
for the ephemeris status or use Cloudwatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: Troubleshooting Invalid Ephemerides
Create a TLE Set Ephemeris via API
The AWS Ground Station boto3 client can be used to upload a two line element (TLE) set ephemeris to AWS Ground Station via
the CreateEphemeris call. This ephemeris will be used in place of the default ephemeris data
for a satellite (see Default Ephemeris Data).
A TLE set is a JSON formatted object that strings one or more TLEs together to construct a continuous trajectory. The TLEs in the TLE set must form a continuous set that we can use to construct a trajectory (i.e. no gaps in time between TLEs in a TLE set). An example TLE set is shown below:
# example_tle_set.json [ { "tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997", "tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906", "validTimeRange": { "startTime": 12345, "endTime": 12346 } }, { "tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997", "tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906", "validTimeRange": { "startTime": 12346, "endTime": 12347 } } ]
Note
The time ranges of the TLEs in a TLE set must match up exactly to be a valid, continuous trajectory.
A TLE set can be uploaded via the AWS Ground Station boto3 client as follows:
tle_ephemeris_id = ground_station_boto3_client.create_ephemeris( name="Example Ephemeris", satelliteId="2e925701-9485-4644-b031-EXAMPLE01", enabled=True, expirationTime=datetime.now(timezone.utc) + timedelta(days=3), priority=2, ephemeris = { "tle": { "tleData": [ { "tleLine1": "1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997", "tleLine2": "2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906", "validTimeRange": { "startTime": datetime.now(timezone.utc), "endTime": datetime.now(timezone.utc) + timedelta(days=7) } } ] } })
This call will return an ephemeris Id that can be used to reference the ephemeris in the future. For example, we can use the provided ephemeris ID from the call above to poll for the status of the ephemeris:
client.describe_ephemeris(ephemerisId=tle_ephemeris_id['ephemerisId'])
An example response from the DescribeEphemeris action is provided below
{ "creationTime": 1620254718.765, "enabled": true, "name": "Example Ephemeris", "ephemerisId": "fde41049-14f7-413e-bd7b-EXAMPLE01", "priority": 2, "status": "VALIDATING", "suppliedData": { "tle": { "ephemerisData": "[{\"tleLine1\": \"1 25994U 99068A 20318.54719794 .00000075 00000-0 26688-4 0 9997\",\"tleLine2": \"2 25994 98.2007 30.6589 0001234 89.2782 18.9934 14.57114995111906\",\"validTimeRange\": {\"startTime\": 1620254712000,\"endTime\": 1620859512000}}]" } } }
It is recommended to poll the DescribeEphemeris route or use Cloudwatch events to track the
status of the uploaded ephemeris as it must go through an asynchronous validation workflow before it is set to
ENABLED and becomes usable for scheduling and executing contacts.
Note that the NORAD ID in all TLEs in the TLE set, 25994 in the examples above, must match the NORAD ID your
satellite has been assigned in the Space Track database.
Uploading Ephemeris data from an S3 bucket
It is also possible to upload an ephemeris file directly from an S3 bucket by pointing to the bucket and object key. AWS Ground Station will retrieve the object on your behalf. Information about the encryption of data at rest in AWS Ground Station is detailed in: Data Encryption At Rest For AWS Ground Station
Below is an example of uploading an OEM ephemeris file from an S3 bucket
s3_oem_ephemeris_id = customer_client.create_ephemeris( name="2022-10-26 S3 OEM Upload", satelliteId="fde41049-14f7-413e-bd7b-EXAMPLE01", enabled=True, expirationTime=datetime.now(timezone.utc) + timedelta(days=5), priority=2, ephemeris = { "oem": { "s3Object": { "bucket": "ephemeris-bucket-for-testing", "key": "test_data.oem", } } })
Below is an example returned data from the DescribeEphemeris action being called for the OEM
ephemeris uploaded in the previous block of example code.
{ "creationTime": 1620254718.765, "enabled": true, "name": "Example Ephemeris", "ephemerisId": "fde41049-14f7-413e-bd7b-EXAMPLE02", "priority": 2, "status": "VALIDATING", "suppliedData": { "oem": { "sourceS3Object": { "bucket": "ephemeris-bucket-for-testing", "key": "test_data.oem" } } }
