Orbit Determination (OD)

Listing OD Assets and Files

The Satcat SDK provides methods for listing your organization’s OD assets and files. To list OD assets, use list_assets:

...
od_assets = client.od.list_assets()

To list OD files, use list_object_files. This returns the files available for the specified object. You can also page, search, and sort the results with count, offset, search, sort_field, and sort_direction.

...
object_id = 12345
od_files = client.od.list_object_files(
    object_id=object_id,
    count=25,
    search="tle",
    sort_field="last_modified",
    sort_direction="desc",
)

Uploading OD Files

To upload a file to be used in OD processing, use upload_file. You will need to specify the NORAD ID of the object the file is for. While you can upload a file for any asset, OD will only be performed for assets contracted with Kayhan Space.

Allowed filename formats

Uploaded OD files must follow one of the supported naming conventions below. Files that do not match these formats will be rejected.

GNSS files:

• gnss_<NORAD>_YYYY_MM_DD_HH_MM_SSZ.(json|csv|navsol)

  • Example: gnss_12345_2025_12_31_00_00_00Z.json

• gnss_<NORAD>_YYYY-MM-DDTHH:MM:SSZ.(json|csv|navsol)

  • Example: gnss_12345_2025-12-31T00:00:00Z.csv

Maneuver files:

• maneuver_<NORAD>_YYYY_MM_DD_HH_MM_SSZ.(opm|txt)

  • Example: maneuver_12345_2025_12_31_00_00_00Z.opm

• maneuver_<NORAD>_YYYY-MM-DDTHH:MM:SSZ.(opm|txt)

  • Example: maneuver_12345_2025-12-31T00:00:00Z.txt

Where:

• <NORAD> is either a 5-digit or 9-digit NORAD catalog ID.

• Timestamps must be UTC and end with Z.

...
object_id = 12345
od_file_content = client.od.upload_file(
    object_id,
    path_or_buf="path/to/file/od_file.json",
    filename="gnss_12345_2025_12_31_00_00_00Z.json",
)

OD Upload Size Limit

The Satcat API enforces a server-side OD upload limit. If an upload exceeds the configured limit, the API returns HTTP 413 with a JSON detail message that includes the uploaded file size and the maximum allowed size. If your upload is too large, reduce the file size by downsampling measurements to approximately one sample every 10 seconds or limiting the amount of historical data included, then submit the file again.

Downloading OD Files and Results

Any file in your organization’s OD S3 bucket can be downloaded using download_file. There is also a convenience method to retrieving recent results of Kayhan’s OD processing using download_recent_files, which will fetch the most recent DEFINITIVE and PREDICTIVE ephemeris for the asset, as well as the generated pdf report if desired.

...
object_id = 12345
od_file_content = client.od.download_file(
    object_id,
    "od_results.json",
)

download_report = True,
number_to_fetch = 1
output_directory = "/tmp/od_downloads"
num_definitive, num_predictive, fetched_report = client.od.download_recent_files(
    object_id,
    report = download_report,
    number = number_to_fetch, # How many recent ephemerides to fetch. Will retrieve as many as are available up to this number.
    output_dir = output_directory, # If omitted, files will be saved to the current working directory
)
print(f"Downloaded {num_definitive} definitive and {num_predictive} predictive ephemerides. Fetched report? {fetched_report}")