The client

class lunaspace.Client

The API with your organisation’s key.

api_key defaults to the environment’s LUNA_API_KEY, base_url to LUNA_API_URL or the service’s address. transport replaces httpx’s (tests). Use it as a context manager, or call close(), to release its connections.

__init__(api_key=None, *, base_url=None, timeout=60.0, transport=None)
Parameters:
  • api_key (str | None)

  • base_url (str | None)

  • timeout (float)

  • transport (BaseTransport | None)

close()

Releases the client’s connections.

Return type:

None

request(method, path, *, json=None, content=None, params=None)

One call of the API: its JSON answer (None for an empty one); a LunaError for an answer that is not a success.

Parameters:
Return type:

Any

fetch(path)

A file of the API’s, as it is, and the name the API gives it.

Parameters:

path (str)

Return type:

tuple[bytes, str | None]

download(path)

A file of the API’s, as it is.

Parameters:

path (str)

Return type:

bytes

save(path, to=None, name=None)

A file of the API’s: written to to (a file; or a directory, under the name the API gives it, else name) and its path returned, or its bytes returned.

Parameters:
Return type:

Path | bytes

wait_until(fetch, done, what, *, timeout, poll, sleep=<built-in function sleep>)

fetch() again every poll seconds until done; WaitTimeout after timeout.

Parameters:
Return type:

J

me()

Your organisation, and the features of its tier.

Return type:

Organisation

profiles()

The kinds of orbit determination the service runs, with their settings.

Return type:

list[Profile]

engines()

The orbit determination engines a run can name.

Return type:

list[Engine]

asset_id(asset)

The id of an asset given as itself, its id or its name.

Parameters:

asset (Asset | str)

Return type:

str

Resources

Each is an attribute of the client: client.assets, client.runs, client.orbits and so on. Wherever a method takes a satellite, it takes the Asset, its id or its name.

class lunaspace.client.Assets

Your satellites.

list()

Your organisation’s satellites.

Return type:

list[Asset]

get(asset)

A satellite by its id or its name.

Parameters:

asset (str)

Return type:

Asset

create(name, *, external_id=None, group=None, norad_id=None, international_designator=None)

A new satellite; group keeps it in a group of that name (a constellation, a mission).

Parameters:
  • name (str)

  • external_id (str | None)

  • group (str | None)

  • norad_id (int | None)

  • international_designator (str | None)

Return type:

Asset

update(asset, **changes)

Change group, norad_id, international_designator or tle_enabled; None clears an identifier or takes the satellite out of its group.

Parameters:
Return type:

Asset

class lunaspace.client.Properties

A satellite’s spacecraft properties, each from the time it is valid.

list(asset)

The satellite’s spacecraft properties, every version.

Parameters:

asset (Asset | str)

Return type:

list[SpacecraftProperties]

add(asset, *, mass_kg, drag_area_m2, srp_area_m2, drag_coefficient=None, reflectivity_coefficient=None, antenna_offset_m=None, valid_from=None)

A new version of the satellite’s spacecraft properties, from valid_from (none: from the start).

Parameters:
Return type:

SpacecraftProperties

class lunaspace.client.Tracking

A satellite’s navigation fixes: CSV (epoch,x,y,z[,vx,vy,vz], ITRF, km) or SP3.

upload(asset, file=None, *, data=None, filename=None, satellite=None)

Upload fixes: a file, or data held in memory with the filename to record (both CSV or SP3); satellite picks one of an SP3 file’s. Uploading the same fixes again returns the first upload.

Parameters:
Return type:

TrackingFile

list(asset, *, limit=100)

The tracking data files uploaded for the satellite, newest first.

Parameters:
Return type:

list[TrackingFile]

class lunaspace.client.Runs

Orbit determinations.

request(asset, arc_start, arc_end, *, setting=None, custom=None, profile=None, engine=None)

Ask for an orbit determination over the arc, from the satellite’s uploads and properties; it is queued, and Run.wait() waits for it. setting names one of the profile’s settings; custom gives the estimation’s settings yourself in its place ({"segment_minutes": 45, ...}: see Profile.custom_settings; the feature od_custom_settings, or FeatureNotIncluded).

Parameters:
Return type:

Run

get(run_id)

A run by its id.

Parameters:

run_id (str)

Return type:

Run

list(asset, *, limit=50, comparisons=False)

The satellite’s runs, the newest first; a comparison’s only if asked for.

Parameters:
Return type:

list[Run]

wait(run, *, timeout=1800.0, poll=5.0, raise_on_failure=True, sleep=<built-in function sleep>)

The run once it has finished: RunFailed if it failed (unless raise_on_failure is False), WaitTimeout if it has not finished in timeout seconds.

Parameters:
Return type:

Run

diagnostics(run)

What an analyst looks at to judge a finished run beyond its gate: the residuals against N(0, 1) and per segment, the estimates with their sigmas, correlations, convergence, the run before’s prediction against its sigmas (feature od_diagnostics).

Parameters:

run (Run | str)

Return type:

Diagnostics

trends(asset, *, limit=60)

The satellite’s latest finished runs, oldest arc first, figure by figure (feature od_trends).

Parameters:
Return type:

list[Trend]

download(run, name, to=None)

A product of the run (oem, residuals, uncertainty, result): written to to (a file, or a directory for the product’s own file name) and its path returned, or its bytes returned.

Parameters:
Return type:

Path | bytes

report(run, to=None)

The run as a report to read and pass on: one self-contained HTML page (the verdict and its checks, the fit, the estimates, the orbit’s uncertainty, the inputs), of a finished run. Written to to (a file, or a directory for <run-id>.html) and its path returned, or its bytes returned.

Parameters:
Return type:

Path | bytes

class lunaspace.client.Schedules

A satellite’s automatic runs.

get(asset)

The satellite’s schedule, or None if it has none.

Parameters:

asset (Asset | str)

Return type:

Schedule | None

set(asset, **fields)

Make or change the schedule: enabled, profile, setting, custom (the estimation’s settings given yourself, as in runs.request; None takes them away), arc_hours, interval_hours, max_wait_hours, prior_covariance, first_arc_start. A schedule that exists keeps what is not given.

Parameters:
Return type:

Schedule

class lunaspace.client.Orbits

A satellite’s current orbit: the accepted run it comes from, and its ephemeris.

get(asset)

The satellite’s orbit, or None before its first accepted run.

Parameters:

asset (Asset | str)

Return type:

Orbit | None

ephemeris(asset, to=None)

The current orbit’s ephemeris (CCSDS OEM): written to to (a file, or a directory for <satellite>.oem), or returned as bytes.

Parameters:
Return type:

Path | bytes

reconstructed(asset, start, end, *, frame='GCRF', covariance=True, step_s=None)

Ask for the satellite’s reconstructed orbit over a span: the fitted arcs of its accepted runs one after another in one ephemeris (CCSDS OEM), never a prediction. Two arcs that overlap meet in the middle of what they share; a time no arc covers stays a gap (pieces, gaps). In frame (“GCRF” or “ITRF”), at step_s (None: the runs’ own time tags), with or without the covariances. .wait() waits for it, .download() gets the file.

Parameters:
Return type:

OrbitFile

reconstructed_list(asset, *, limit=20)

The reconstructed orbits asked for of the satellite, the latest first.

Parameters:
Return type:

list[OrbitFile]

drag_coefficients(asset, *, start=None, end=None)

The history of the satellite’s drag coefficient: what each accepted run estimated over its arc, with its sigma, the oldest arc first (start, end: the arcs that end after, start before). lunaspace.frames.drag_coefficients makes a data frame of it.

Parameters:
Return type:

list[DragCoefficient]

drag_coefficients_file(asset, to=None, *, start=None, end=None)

The drag coefficient’s history as a table (CSV): written to to (a file, or a directory for the name the API gives it), or returned as bytes.

Parameters:
Return type:

Path | bytes

class lunaspace.client.Stations

The organisation’s ground stations, and the ones each satellite uses.

list()

Your organisation’s ground stations.

Return type:

list[Station]

get(station_id)

A station by its id.

Parameters:

station_id (str)

Return type:

Station

create(name, *, latitude_deg=None, longitude_deg=None, height_m=None, cartesian_m=None, mask_deg=None, horizon=None, downlink_frequency_hz=None)

A station from its geodetic position (WGS84), or its Cartesian one in ITRF (cartesian_m={"x": ..., "y": ..., "z": ...}); a mask in degrees, or a horizon of {"azimuth_deg", "elevation_deg"} points.

Parameters:
Return type:

Station

update(station, **fields)

Replace the station’s description with fields (the same as create’s).

Parameters:
Return type:

Station

delete(station)

Removes a station.

Parameters:

station (Station | str)

Return type:

None

catalogue(query=None)

The service’s catalogue of sites (open sources), by a search of name or provider, to fill a station in from.

Parameters:

query (str | None)

Return type:

list[CatalogueStation]

of(asset)

The stations the satellite uses.

Parameters:

asset (Asset | str)

Return type:

list[Station]

assign(asset, stations, *, passes_days=None, light_time=None)

The stations the satellite uses (its passes are computed over them with each orbit), and optionally the days ahead (1 to 7) and the light time (none, receive, transmit).

Parameters:
Return type:

list[Station]

class lunaspace.client.PassesResource

A satellite’s passes over its stations, made with each orbit or on request.

get(asset, *, run=None)

The latest passes of the current orbit (or of run), or None.

Parameters:
Return type:

Passes | None

request(asset)

Compute them again for the current orbit; .wait() waits for them.

Parameters:

asset (Asset | str)

Return type:

Passes

by_id(passes_id)

Passes by their id.

Parameters:

passes_id (str)

Return type:

Passes

class lunaspace.client.OrbitEventsResource

A satellite’s orbit events: its eclipses, its crossings of the equator with the beta angle, its orbits one by one and its ground track. Made with each orbit where the satellite has orbit_events_enabled (assets.update(asset, orbit_events_enabled=True)), or on request.

get(asset, *, run=None)

The latest events of the current orbit (or of run), or None.

Parameters:
Return type:

OrbitEvents | None

request(asset)

Compute them again for the current orbit; .wait() waits for them.

Parameters:

asset (Asset | str)

Return type:

OrbitEvents

by_id(events_id)

Orbit events by their id.

Parameters:

events_id (str)

Return type:

OrbitEvents

class lunaspace.client.OrbitFiles

A run’s orbit in another form, made on request: its ephemeris written again, or one state of it as a CCSDS OPM. (A satellite’s reconstructed orbit, which is made of several runs, is asked for with orbits.reconstructed.)

request(run, format='oem', *, frame='GCRF', covariance=True, step_s=None, start=None, end=None, epoch=None)

Ask for the run’s orbit in another form; .wait() waits for it, .download() gets the file.

format “oem”: the run’s ephemeris (its fitted arc and its prediction) as a CCSDS OEM in frame (“GCRF”, or “ITRF”: the Earth-fixed frame), at step_s (1 to 3600; None: the run’s own time tags), from start to end (None: all of it), with or without its covariances.

format “opm”: the state at epoch (None: the end of the run’s arc) as a CCSDS Orbit Parameter Message, with the osculating Keplerian elements (in GCRF), the spacecraft’s parameters (the mass as it is at the epoch), the covariance where the ephemeris has one there, and the run’s manoeuvres after the epoch, each with its mass change.

Parameters:
Return type:

OrbitFile

list(run)

The orbit files asked for of the run, the latest first.

Parameters:

run (Run | str)

Return type:

list[OrbitFile]

get(orbit_file_id)

An orbit file by its id.

Parameters:

orbit_file_id (str)

Return type:

OrbitFile

class lunaspace.client.TleResource

A satellite’s TLEs and OMMs, fitted to an orbit.

get(asset, *, run=None)

The latest TLE of the current orbit (or of run), or None.

Parameters:
Return type:

Tle | None

request(asset)

Fit one to the current orbit, with the satellite’s identifiers; .wait().

Parameters:

asset (Asset | str)

Return type:

Tle

by_id(tle_id)

A TLE by its id.

Parameters:

tle_id (str)

Return type:

Tle

class lunaspace.client.Plans

Manoeuvre plans from a satellite’s current orbit (advice only).

request(asset, *, window_start=None, window_end=None, **targets)

Ask for burns in the window that reach the targets, each a dictionary as the API takes it: semi_major_axis={"delta_m": 50}, inclination={"value_deg": 87.35}, node={...}, phase={...}, ground_track={...}, eccentricity_vector={...}; and strategy, elements, prediction_hours, burn_sigma_mm_s, cd_sigma.

Parameters:
Return type:

Plan

list(asset, *, limit=20)

The satellite’s plans, newest first.

Parameters:
Return type:

list[Plan]

get(plan_id)

A plan by its id.

Parameters:

plan_id (str)

Return type:

Plan

class lunaspace.client.Comparisons

One arc determined with several settings, set side by side.

request(asset, arc_start, arc_end, *, settings=None, engines=None, profile=None)

Compare settings (the profile’s few when none are named) over the arc.

Parameters:
Return type:

Comparison

list(asset, *, limit=20)

The satellite’s comparisons, newest first.

Parameters:
Return type:

list[Comparison]

get(comparison_id)

A comparison by its id.

Parameters:

comparison_id (str)

Return type:

Comparison

wait(comparison, *, timeout=3600.0, poll=10.0, sleep=<built-in function sleep>)

The comparison once every setting has finished (or been skipped).

Parameters:
Return type:

Comparison

class lunaspace.client.Manoeuvres

The manoeuvres a satellite made or will make, as you report them.

list(asset, *, limit=100)

The manoeuvres reported for the satellite.

Parameters:
Return type:

list[Manoeuvre]

report(asset, epoch, *, radial_m_s=0.0, along_track_m_s=0.0, cross_track_m_s=0.0, sigma_m_s=None, delta_mass_kg=None, specific_impulse_s=None)

A burn at epoch, its velocity change in the orbit’s axes [m/s]: estimated by the runs whose arc holds it, applied in the predictions of those before it. What it spent, in one of two ways: delta_mass_kg (the mass change, negative: the propellant as your bookkeeping has it) or specific_impulse_s (the thruster’s: the mass change follows from the velocity change). The satellite is that much lighter from the burn on; with neither, its mass stays.

Parameters:
Return type:

Manoeuvre

delete(manoeuvre)

Removes a reported manoeuvre (to correct one: delete it, then report it again).

Parameters:

manoeuvre (Manoeuvre | str)

Return type:

None

class lunaspace.client.Webhooks

Addresses the service tells when a run finishes or wants a look.

list()

Your organisation’s webhooks, with when an event last arrived or why the latest did not.

Return type:

list[Webhook]

create(url, *, events=None)

A webhook for url (https) and events (od.completed, od.flagged; both when none are named). Keep its secret: it is shown once.

Parameters:
Return type:

NewWebhook

delete(webhook)

Removes a webhook.

Parameters:

webhook (Webhook | str)

Return type:

None

ping(webhook)

Send a ping event to the webhook’s address; the delivery’s id.

Parameters:

webhook (Webhook | str)

Return type:

str