Quickstart

From an API key to a predicted ephemeris of your satellite, in five steps. You need navigation fixes from the satellite’s GNSS receiver for at least three hours, and a few figures about the spacecraft. Times are UTC, written as 2026-10-01T00:00:00Z (or given as aware datetime objects).

from lunaspace import Client

client = Client()  # the key from LUNA_API_KEY (see Installation)

1. Register the satellite

satellite = client.assets.create("MYSAT-1", external_id="2026-001A")

The name becomes the object name in your ephemeris files, and external_id (optional, the international designator) their object ID. Everywhere the client wants a satellite you may give the Asset itself, its id or its name: client.assets.get("MYSAT-1").

2. Describe the spacecraft

client.properties.add(
    satellite,
    mass_kg=430,
    drag_area_m2=1.0,
    srp_area_m2=4.0,
    antenna_offset_m={"along_track": 0.31},
)

Field

Meaning

mass_kg

Mass of the spacecraft

drag_area_m2

Cross-section facing the direction of flight

srp_area_m2

Cross-section facing the Sun

drag_coefficient

Optional starting value (2.2). It is estimated in every run

reflectivity_coefficient

Optional (1.3)

antenna_offset_m

Optional: where the GNSS antenna sits relative to the centre of mass, as radial, along_track and cross_track in metres

valid_from

Optional: from when these values hold

When something changes, add the properties again with valid_from. Each run uses the values valid at the start of its arc.

3. Upload the navigation fixes

upload = client.tracking.upload(satellite, "fixes.csv")
print(upload.fix_count, upload.first_epoch, upload.last_epoch)

The file is a CSV with one fix per line: the epoch with its time scale, and the position in the Earth-fixed frame (ITRF) in kilometres. SP3 files are accepted too (Tracking data).

# frame: ITRF
# units: km
epoch,x,y,z
2026-10-01T00:00:18 GPS,-2749.380960,4977.646860,3825.584070
2026-10-01T00:00:28 GPS,-2769.338560,5014.925560,3762.195550

A file that cannot be used is refused with the line and the reason, as an InvalidRequest. Uploading the same file twice is harmless.

4. Ask for the orbit determination

run = client.runs.request(satellite, "2026-10-01T00:00:00Z", "2026-10-02T00:00:00Z")

The arc is the span of data to fit, between 3 and 72 hours; a day is a good choice. The request returns at once: the work happens in the background and takes about ten seconds for a day of data.

5. Fetch the result

run = run.wait()  # asks until it has finished; RunFailed if it failed
print(run.status, run.accepted, run.weighted_rms)
run.download("oem", "ephemeris.oem")  # or a directory, or no target for the bytes

Product

What it is

oem

The orbit: the fitted arc and the 24 hours after it, as a CCSDS Orbit Ephemeris Message with its covariance

uncertainty

How well the orbit is known, as a table (CSV): the standard deviations of the position and the velocity in the orbit’s radial, along-track and cross-track axes

residuals

For every fix: whether it was used, and how far it lies from the fitted orbit (CSV)

result

The full result of the determination (JSON)

run.accepted says whether the run passed its acceptance check and can be trusted without a closer look; Orbit determination runs explains how to read a run. To have the service run every day as your data arrives, give the satellite a schedule: Automatic runs.