# Provide custom ephemeris data
**Important**
The ephemeris API is currently in a Preview state
Access to the Ephemeris API is provided only on an as-needed basis. If you require the ability to upload custom ephemeris data, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will work with you to enable this capability for your specific requirements.
## 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](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)). We support receiving ephemeris data in Orbit Ephemeris Message (OEM), two-line element (TLE), and azimuth elevation formats.
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
Uploading custom ephemerides can improve the quality of tracking, handle operations where no [Space-Track](https://www.space-track.org/) ephemerides are available to AWS Ground Station, and account for maneuvers.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## Example: Using customer-provided ephemerides with AWS Ground Station
For more detailed instructions for using customer-provided ephemerides with AWS Ground Station, see [Using customer-provided ephemerides with AWS Ground Station](https://aws.amazon.com/blogs/publicsector/using-customer-provided-ephemerides-with-aws-ground-station/) and it's associated GitHub repository [aws-samples/aws-groundstation-cpe](https://github.com/aws-samples/aws-groundstation-cpe).
# Provide TLE ephemeris data
**Important**
The ephemeris API is currently in a Preview state
Access to the Ephemeris API is provided only on an as-needed basis. If you require the ability to upload custom ephemeris data, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will work with you to enable this capability for your specific requirements.
## Overview
Two-line element (TLE) sets are a standardized format for describing satellite orbits. The Ephemeris API allows TLE ephemerides to be uploaded to AWS Ground Station for use with a satellite. These ephemerides override the default ephemerides from [Space-Track](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)).
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
Uploading custom TLE ephemerides can improve the quality of tracking, handle early operations where no [Space-Track](https://www.space-track.org/) ephemerides are available to AWS Ground Station, and account for maneuvers.
**Note**
When providing custom ephemeris before a satellite catalog number is assigned for your satellite, you can use `00000` for the satellite catalog number field of the TLE, and `000` for the launch number portion of the international designator field of the TLE (e.g. `24000A` for a vehicle launched in 2024).
For more information about the format of TLEs, see [Two-line element set](https://en.wikipedia.org/wiki/Two-line_element_set).
## Creating a TLE ephemeris
A TLE ephemeris can be created using the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## Example: Create a two-line element (TLE) set ephemeris via API
The AWS SDKs, and CLI can be used to upload a two line element (TLE) set ephemeris to AWS Ground Station via the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) call. This ephemeris will be used in place of the default ephemeris data for a satellite (see [Default ephemeris data](default-ephemeris-data.md)). This example shows how to do this using the [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/pythonsdk).
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:
```
[
{
"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:
```
import boto3
from datetime import datetime, timedelta, timezone
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create TLE ephemeris
tle_ephemeris = ground_station_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),
},
}
]
}
},
)
print(f"Created TLE ephemeris with ID: {tle_ephemeris['ephemerisId']}")
```
This call will return an ephemerisId that can be used to reference the ephemeris in the future. For example, we can use the provided ephemerisId from the call above to poll for the status of the ephemeris:
```
import boto3
from datetime import datetime, timedelta, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# First, create a TLE ephemeris
print("Creating TLE ephemeris...")
tle_ephemeris = ground_station_client.create_ephemeris(
name="Example TLE Ephemeris for Description",
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),
},
}
]
}
},
)
ephemeris_id = tle_ephemeris["ephemerisId"]
print(f"Created TLE ephemeris with ID: {ephemeris_id}")
# Describe the ephemeris immediately to check initial status
print("Describing ephemeris...")
response = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)
print(f"Ephemeris ID: {response['ephemerisId']}")
print(f"Name: {response['name']}")
print(f"Status: {response['status']}")
```
An example response from the [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 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](https://www.space-track.org/) database.
## Example: Uploading TLE ephemeris data from an S3 bucket
It is also possible to upload a TLE 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](security.encryption-at-rest.md).
Below is an example of uploading a TLE ephemeris file from an S3 bucket
```
import boto3
from datetime import datetime, timedelta, timezone
import json
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "ephemeris-bucket"
object_key = "test_data.tle"
# Create sample TLE set data
# Note: For actual satellites, use real TLE data from sources like Space-Track
tle_set_data = [
{
"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=3),
},
},
{
"tleLine1": "1 25994U 99068A 20321.54719794 .00000075 00000-0 26688-4 0 9998",
"tleLine2": "2 25994 98.2007 33.6589 0001234 89.2782 18.9934 14.57114995112342",
"validTimeRange": {
"startTime": datetime.now(timezone.utc) + timedelta(days=3),
"endTime": datetime.now(timezone.utc) + timedelta(days=7),
},
},
]
# Convert to JSON string for upload
tle_json = json.dumps(tle_set_data, indent=2)
# Upload sample TLE data to S3
print(f"Uploading TLE set data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name, Key=object_key, Body=tle_json, ContentType="application/json"
)
print("TLE set data uploaded successfully to S3")
print(f"Uploaded {len(tle_set_data)} TLE entries covering 7 days")
# Create TLE ephemeris from S3
print("Creating TLE ephemeris from S3...")
s3_tle_ephemeris = ground_station_client.create_ephemeris(
name="2022-11-05 S3 TLE Upload",
satelliteId="fde41049-14f7-413e-bd7b-EXAMPLE01",
enabled=True,
expirationTime=datetime.now(timezone.utc) + timedelta(days=5),
priority=2,
ephemeris={"tle": {"s3Object": {"bucket": bucket_name, "key": object_key}}},
)
print(f"Created TLE ephemeris with ID: {s3_tle_ephemeris['ephemerisId']}")
```
# Provide OEM ephemeris data
**Important**
The ephemeris API is currently in a Preview state
Access to the Ephemeris API is provided only on an as-needed basis. If you require the ability to upload custom ephemeris data, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will work with you to enable this capability for your specific requirements.
## Overview
Orbit Ephemeris Message (OEM) is a standardized format for representing spacecraft trajectory data. The Ephemeris API allows OEM ephemerides to be uploaded to AWS Ground Station for use with a satellite. These ephemerides override the default ephemerides from [Space-Track](https://www.space-track.org/) (see: [Default ephemeris data](default-ephemeris-data.md)).
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
Uploading custom OEM ephemerides can improve the quality of tracking, handle early operations where no [Space-Track](https://www.space-track.org/) ephemerides are available to AWS Ground Station, and account for maneuvers.
**Note**
When providing custom ephemeris before a satellite catalog number is assigned for your satellite, you can use `satelliteId` for the `OBJECT_ID` portion of the OEM.
For more information about the format of OEMs, see [OEM ephemeris format](#oem-ephemeris-format).
## OEM ephemeris format
AWS Ground Station processes OEM Customer Provided Ephemerides according to the [CCSDS standard](https://ccsds.org/Pubs/502x0b3e1.pdf) with some extra restrictions. OEM files should be in KVN format. The following table outlines the different fields in an OEM and how AWS Ground Station differs from the CCSDS standard.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/ground-station/latest/ug/providing-oem-ephemeris-data.html)
\$1 If any rows that aren't supported by AWS Ground Station are included in the provided OEM, the OEM will fail validation.
The important deviations from the CCSDS standard for AWS Ground Station are:
+ `CCSDS_OEM_VERS` is required to be `2.0`.
+ `REF_FRAME` is required to be either `EME2000` or ` ITRF2000`.
+ `REF_FRAME_EPOCH` is not supported by AWS Ground Station.
+ `CENTER_NAME` is required to be `Earth`.
+ `TIME_SYSTEM` is required to be `UTC`.
+ `INTERPOLATION` and `INTERPOLATION_DEGREE` are both required for AWS Ground Station customer provided ephemeris.
+ AWS Ground Station deviates from CCSDS 5.2.4.7 by allowing OEM data blocks that do not contain enough ephemeris data records to perform interpolation at the specified `INTERPOLATION_DEGREE`. In this case, AWS Ground Station will use the highest interpolation degree possible that is less than or equal to the specified `INTERPOLATION_DEGREE`.
## Example OEM ephemeris in KVN format
Following is a truncated example of an OEM ephemeris in KVN format for the JPSS-1 public broadcaster satellite.
```
CCSDS_OEM_VERS = 2.0
COMMENT Orbit data are consistent with planetary ephemeris DE-430
CREATION_DATE = 2024-07-22T05:20:59
ORIGINATOR = Raytheon-JPSS/CGS
META_START
OBJECT_NAME = J1
OBJECT_ID = 2017-073A
CENTER_NAME = Earth
REF_FRAME = EME2000
TIME_SYSTEM = UTC
START_TIME = 2024-07-22T00:00:00.000000
STOP_TIME = 2024-07-22T00:06:00.000000
INTERPOLATION = Lagrange
INTERPOLATION_DEGREE = 5
META_STOP
2024-07-22T00:00:00.000000 5.905147360000000e+02 -1.860082793999999e+03 -6.944807075000000e+03 -5.784245796000000e+00 4.347501391999999e+00 -1.657256863000000e+00
2024-07-22T00:01:00.000000 2.425572045154201e+02 -1.595860765983339e+03 -7.030938457373539e+03 -5.810660250794190e+00 4.457103652219009e+00 -1.212889340333023e+00
2024-07-22T00:02:00.000000 -1.063224256538050e+02 -1.325569732497146e+03 -7.090262617183503e+03 -5.814973972202444e+00 4.549739160042560e+00 -7.639633689161465e-01
2024-07-22T00:03:00.000000 -4.547973959231161e+02 -1.050238305712201e+03 -7.122556683227951e+03 -5.797176562437553e+00 4.625064829516728e+00 -3.121687831090774e-01
2024-07-22T00:04:00.000000 -8.015427368657785e+02 -7.709137891269565e+02 -7.127699477194810e+03 -5.757338007808417e+00 4.682800822515077e+00 1.407953645161997e-01
2024-07-22T00:05:00.000000 -1.145240083085062e+03 -4.886583601179489e+02 -7.105671911254255e+03 -5.695608435738609e+00 4.722731329786999e+00 5.932259682105052e-01
2024-07-22T00:06:00.000000 -1.484582479061495e+03 -2.045451985605701e+02 -7.056557069672793e+03 -5.612218005854990e+00 4.744705579872771e+00 1.043421397392599e+00
```
## Creating an OEM ephemeris
An OEM ephemeris can be created using the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) 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](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## Example: Uploading OEM ephemeris data from an S3 bucket
It is also possible to upload an OEM 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](security.encryption-at-rest.md).
Below is an example of uploading an OEM ephemeris file from an S3 bucket
```
import boto3
from datetime import datetime, timedelta, timezone
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "ephemeris-bucket"
object_key = "test_data.oem"
# Create sample OEM data in KVN format
oem_data = """CCSDS_OEM_VERS = 2.0
COMMENT Orbit data are consistent with planetary ephemeris DE-430
CREATION_DATE = 2024-07-22T05:20:59
ORIGINATOR = Raytheon-JPSS/CGS
META_START
OBJECT_NAME = J1
OBJECT_ID = 2017-073A
CENTER_NAME = Earth
REF_FRAME = EME2000
TIME_SYSTEM = UTC
START_TIME = 2024-07-22T00:00:00.000000
STOP_TIME = 2024-07-22T00:06:00.000000
INTERPOLATION = Lagrange
INTERPOLATION_DEGREE = 5
META_STOP
2024-07-22T00:00:00.000000 5.905147360000000e+02 -1.860082793999999e+03 -6.944807075000000e+03 -5.784245796000000e+00 4.347501391999999e+00 -1.657256863000000e+00
2024-07-22T00:01:00.000000 2.425572045154201e+02 -1.595860765983339e+03 -7.030938457373539e+03 -5.810660250794190e+00 4.457103652219009e+00 -1.212889340333023e+00
2024-07-22T00:02:00.000000 -1.063224256538050e+02 -1.325569732497146e+03 -7.090262617183503e+03 -5.814973972202444e+00 4.549739160042560e+00 -7.639633689161465e-01
2024-07-22T00:03:00.000000 -4.547973959231161e+02 -1.050238305712201e+03 -7.122556683227951e+03 -5.797176562437553e+00 4.625064829516728e+00 -3.121687831090774e-01
2024-07-22T00:04:00.000000 -8.015427368657785e+02 -7.709137891269565e+02 -7.127699477194810e+03 -5.757338007808417e+00 4.682800822515077e+00 1.407953645161997e-01
2024-07-22T00:05:00.000000 -1.145240083085062e+03 -4.886583601179489e+02 -7.105671911254255e+03 -5.695608435738609e+00 4.722731329786999e+00 5.932259682105052e-01
2024-07-22T00:06:00.000000 -1.484582479061495e+03 -2.045451985605701e+02 -7.056557069672793e+03 -5.612218005854990e+00 4.744705579872771e+00 1.043421397392599e+00
"""
# Upload sample OEM data to S3
print(f"Uploading OEM data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name, Key=object_key, Body=oem_data, ContentType="text/plain"
)
print("OEM data uploaded successfully to S3")
# Create OEM ephemeris from S3
print("Creating OEM ephemeris from S3...")
s3_oem_ephemeris = ground_station_client.create_ephemeris(
name="2024-07-22 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": bucket_name, "key": object_key}}},
)
print(f"Created OEM ephemeris with ID: {s3_oem_ephemeris['ephemerisId']}")
```
Below is an example returned data from the [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) 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"
}
}
}
}
```
# Provide azimuth elevation ephemeris data
**Important**
The azimuth elevation ephemeris feature is currently in a Preview state and requires explicit onboarding.
Azimuth elevation ephemeris functionality is under strict access control for a limited number of pre-determined, specialized use cases. Access is significantly more restrictive than for standard customer-provided ephemeris capabilities. For more information about approved use cases and the access request process, please open an AWS Support ticket through the [AWS Support Center Console](https://console.aws.amazon.com/support). Our team will guide you through the approval process for specialized use cases.
## Overview
Azimuth elevation ephemeris provides a way to directly specify antenna pointing directions without providing satellite orbital information. Instead of uploading ephemeris data that describes a satellite's orbit, you provide time-tagged azimuth and elevation angles that tell the antenna exactly where to point throughout a contact.
AWS Ground Station treats ephemerides as [Individualized Usage Data](https://aws.amazon.com/service-terms). If you use this optional feature, AWS will use your ephemeris data to provide troubleshooting support.
This approach is particularly useful for the following scenarios:
+ *Early operations support:* During Launch and Early Orbit Phase (LEOP) when precise orbital data is unavailable, or orbital parameters are rapidly changing.
+ *Custom pointing patterns:* Implementing specific pointing sequences for antenna testing or non-standard operations.
**Note**
When using azimuth elevation ephemeris, the satellite ARN may be omitted from the contact reservation request. If the satellite ARN is not omitted, it will still be included as part of the contact data, but the azimuth elevation ephemeris will be used for antenna pointing rather than performing ephemeris priority resolution. The azimuth elevation ephemeris is associated with a specific ground station and defines the antenna pointing directions for that location.
## Azimuth elevation ephemeris data format
Azimuth elevation ephemeris data consists of time-tagged azimuth and elevation values organized into segments. Each segment contains a series of azimuth and elevation angles that cover a specific time range.
The key components of azimuth elevation ephemeris data are:
+ *Ground Station:* The specific ground station where this azimuth elevation ephemeris will be used.
+ *Angle Unit:* The unit of measurement for angles (`DEGREE_ANGLE` or `RADIAN`).
+ *Segments:* One or more time-bounded collections of azimuth and elevation angles.
+ *Time-tagged angles:* Individual azimuth and elevation values with associated timestamps.
Each segment requires:
+ A reference epoch (the base time for the segment)
+ A valid time range (start and end times for the segment)
+ At least 5 time-tagged azimuth/elevation pairs
Azimuth elevation constraints:
+ Azimuth in degrees: -180° to 360°
+ Azimuth in radians: -π to 2π
+ Elevation in degrees: -90° to 90°
+ Elevation in radians: -π/2 to π/2
+ Time values must be in ascending order within each segment
+ Segments must not overlap in time
For more information, see the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API documentation and the [TimeAzEl](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_TimeAzEl.html) data type.
## Creating azimuth elevation ephemeris
Azimuth elevation ephemeris is created using the same [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API action, but with the `azEl` ephemeris type. The key differences from TLE and OEM ephemeris are:
+ You must specify a `groundStation` parameter
+ The `satelliteId` parameter must be omitted from the request
+ Priority settings do not apply (each azimuth elevation ephemeris is specific to a ground station)
+ Each segment must contain at least 5 azimuth/elevation points to support 4th order Lagrange interpolation
+ Additional limits and requirements are detailed in the [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html) API documentation
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. An ephemeris will only be used for contacts after it has passed this workflow and its status becomes `ENABLED`. You should poll [DescribeEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_DescribeEphemeris.html) for the ephemeris status or use CloudWatch events to track the ephemeris' status changes.
To troubleshoot an invalid ephemeris see: [Troubleshoot invalid ephemerides](troubleshooting-invalid-ephemerides.md)
## Example: Create azimuth elevation ephemeris via API
The following example shows how to create an azimuth elevation ephemeris using the AWS SDK for Python (Boto3):
```
import boto3
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Create azimuth elevation ephemeris
azimuth_elevation_ephemeris = ground_station_client.create_ephemeris(
name="Azimuth Elevation for Ohio Ground Station",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
print(f"Created ephemeris with ID: {azimuth_elevation_ephemeris['ephemerisId']}")
```
In this example:
+ The azimuth elevation data is associated with the "Ohio 1" ground station
+ Angles are specified in degrees
+ The segment covers a 15-minute period
+ The `dt` values are atomic seconds offset from the reference epoch
+ Six azimuth/elevation pairs are provided (minimum is 5)
## Example: Upload azimuth elevation data from S3
For larger datasets, you can upload azimuth elevation data from an S3 bucket:
```
import boto3
import json
# Create AWS clients
s3_client = boto3.client("s3")
ground_station_client = boto3.client("groundstation")
# Define S3 bucket and key
bucket_name = "azimuth-elevation-bucket"
object_key = "singapore-azimuth-elevation.json"
# Create sample azimuth elevation data
azimuth_elevation_data = {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
},
{
"referenceEpoch": "2024-03-15T10:15:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:15:00Z",
"endTime": "2024-03-15T10:30:00Z",
},
"azElList": [
{"dt": 0.0, "az": 70.0, "el": 35.0},
{"dt": 180.0, "az": 75.0, "el": 40.0},
{"dt": 360.0, "az": 80.0, "el": 45.0},
{"dt": 540.0, "az": 85.0, "el": 50.0},
{"dt": 720.0, "az": 90.0, "el": 55.0},
{"dt": 900.0, "az": 95.0, "el": 50.0},
],
},
],
}
# Upload sample data to S3
print(f"Uploading azimuth elevation data to s3://{bucket_name}/{object_key}")
s3_client.put_object(
Bucket=bucket_name,
Key=object_key,
Body=json.dumps(azimuth_elevation_data, indent=2),
ContentType="application/json",
)
print("Sample data uploaded successfully to S3")
# Create azimuth elevation ephemeris from S3
print("Creating azimuth elevation ephemeris from S3...")
s3_azimuth_elevation_ephemeris = ground_station_client.create_ephemeris(
name="Large Azimuth Elevation Dataset",
ephemeris={
"azEl": {
"groundStation": "Singapore 1",
"data": {"s3Object": {"bucket": bucket_name, "key": object_key}},
}
},
)
print(f"Created ephemeris with ID: {s3_azimuth_elevation_ephemeris['ephemerisId']}")
```
The S3 object should contain a JSON structure with the azimuth elevation data in the same format as shown in the direct upload example.
## Reserving contacts with azimuth elevation ephemeris
When using an azimuth elevation ephemeris to reserve a contact, the process differs from TLE and OEM ephemeris:
1. Create the azimuth elevation ephemeris using [CreateEphemeris](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_CreateEphemeris.html)
1. Wait for the ephemeris to reach `ENABLED` status
1. Reserve the contact using [ReserveContact](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ReserveContact.html) with tracking overrides
Example of reserving a contact with azimuth elevation ephemeris:
```
import boto3
from datetime import datetime
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# First, create an azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
create_ephemeris_response = ground_station_client.create_ephemeris(
name="Azimuth Elevation for Contact Reservation",
ephemeris={
"azEl": {
"groundStation": "Ohio 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-03-15T10:00:00Z",
"validTimeRange": {
"startTime": "2024-03-15T10:00:00Z",
"endTime": "2024-03-15T10:15:00Z",
},
"azElList": [
{"dt": 0.0, "az": 45.0, "el": 10.0},
{"dt": 180.0, "az": 50.0, "el": 15.0},
{"dt": 360.0, "az": 55.0, "el": 20.0},
{"dt": 540.0, "az": 60.0, "el": 25.0},
{"dt": 720.0, "az": 65.0, "el": 30.0},
{"dt": 900.0, "az": 70.0, "el": 35.0},
],
}
],
}
},
}
},
)
ephemeris_id = create_ephemeris_response["ephemerisId"]
print(f"Created ephemeris with ID: {ephemeris_id}")
# Wait for ephemeris to become ENABLED
print("Waiting for ephemeris to become ENABLED...")
while True:
status = ground_station_client.describe_ephemeris(ephemerisId=ephemeris_id)[
"status"
]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
raise RuntimeError(f"Ephemeris failed: {status}")
time.sleep(5)
# Reserve contact with azimuth elevation ephemeris
print("Reserving contact...")
contact = ground_station_client.reserve_contact(
# Note: satelliteArn is omitted when using azimuth elevation ephemeris
missionProfileArn="arn:aws:groundstation:us-east-2:111122223333:mission-profile/example-mission-profile",
groundStation="Ohio 1",
startTime=datetime(2024, 3, 15, 10, 0, 0),
endTime=datetime(2024, 3, 15, 10, 15, 0),
trackingOverrides={"programTrackSettings": {"azEl": {"ephemerisId": ephemeris_id}}},
)
print(f"Reserved contact with ID: {contact['contactId']}")
```
**Note**
The `satelliteArn` parameter may be omitted when reserving a contact with azimuth elevation ephemeris. The antenna will follow the specified azimuth and elevation angles during the contact.
## Listing available contacts
When using azimuth elevation ephemeris, the [ListContacts](https://docs.aws.amazon.com/ground-station/latest/APIReference/API_ListContacts.html) API requires specific parameters:
+ The `satelliteArn` parameter may be omitted from the request
+ You must provide an `ephemeris` parameter with the azimuth elevation ephemeris ID to specify which ephemeris to use
+ Available contact windows show when the provided azimuth and elevation angles are above the [site mask](https://docs.aws.amazon.com/ground-station/latest/ug/locations.site-masks.html) of the requested ground station
+ You must still provide `groundStation` and `missionProfileArn`
Example of creating an azimuth elevation ephemeris and listing available contacts with it:
```
import boto3
from datetime import datetime, timezone
import time
# Create AWS Ground Station client
ground_station_client = boto3.client("groundstation")
# Step 1: Create azimuth elevation ephemeris
print("Creating azimuth elevation ephemeris...")
ephemeris_response = ground_station_client.create_ephemeris(
name="Stockholm AzEl Ephemeris",
ephemeris={
"azEl": {
"groundStation": "Stockholm 1",
"data": {
"azElData": {
"angleUnit": "DEGREE_ANGLE",
"azElSegmentList": [
{
"referenceEpoch": "2024-04-01T12:00:00Z",
"validTimeRange": {
"startTime": "2024-04-01T12:00:00Z",
"endTime": "2024-04-01T12:30:00Z",
},
"azElList": [
{"dt": 0.0, "az": 30.0, "el": 15.0},
{"dt": 360.0, "az": 45.0, "el": 30.0},
{"dt": 720.0, "az": 60.0, "el": 45.0},
{"dt": 1080.0, "az": 75.0, "el": 35.0},
{"dt": 1440.0, "az": 90.0, "el": 20.0},
{"dt": 1800.0, "az": 105.0, "el": 10.0},
],
}
],
}
},
}
},
)
ephemeris_id = ephemeris_response["ephemerisId"]
print(f"Created ephemeris: {ephemeris_id}")
# Step 2: Wait for ephemeris to become ENABLED
print("Waiting for ephemeris to become ENABLED...")
while True:
describe_response = ground_station_client.describe_ephemeris(
ephemerisId=ephemeris_id
)
status = describe_response["status"]
if status == "ENABLED":
print("Ephemeris is ENABLED")
break
elif status in ["INVALID", "ERROR"]:
# Check for validation errors
if "invalidReason" in describe_response:
print(f"Ephemeris validation failed: {describe_response['invalidReason']}")
raise RuntimeError(f"Ephemeris failed with status: {status}")
print(f"Current status: {status}, waiting...")
time.sleep(5)
# Step 3: List available contacts using the azimuth elevation ephemeris
print("Listing available contacts with azimuth elevation ephemeris...")
# Convert epoch timestamps to datetime objects
start_time = datetime.fromtimestamp(1760710513, tz=timezone.utc)
end_time = datetime.fromtimestamp(1760883313, tz=timezone.utc)
contacts_response = ground_station_client.list_contacts(
startTime=start_time,
endTime=end_time,
groundStation="Stockholm 1",
statusList=["AVAILABLE"],
ephemeris={"azEl": {"id": ephemeris_id}},
# satelliteArn is optional
satelliteArn="arn:aws:groundstation::111122223333:satellite/a88611b0-f755-404e-b60d-57d8aEXAMPLE",
missionProfileArn="arn:aws:groundstation:eu-north-1:111122223333:mission-profile/966b72f6-6d82-4e7e-b072-f8240EXAMPLE",
)
# Process the results
if contacts_response["contactList"]:
print(f"Found {len(contacts_response['contactList'])} available contacts:")
for contact in contacts_response["contactList"]:
print(f" - Contact from {contact['startTime']} to {contact['endTime']}")
print(
f" Max elevation: {contact.get('maximumElevation', {}).get('value', 'N/A')}°"
)
else:
print("No available contacts found for the specified azimuth elevation ephemeris")
```
**Note**
The `ephemeris` parameter with the azimuth elevation ID must be provided when listing contacts to specify which azimuth elevation ephemeris should be used for determining contact windows. If the `satelliteArn` is included, it will be associated with the contact data, but the azimuth elevation ephemeris will be used for antenna pointing rather than performing ephemeris priority resolution.