odms-client

Python client for the ODMS orbital-data API.

No dependencies. It is written against urllib because every service in the estate depends on ODMS, and a shared client that drags a dependency tree into each of their resolvers does not get shared — it gets copy-pasted, and then there are five subtly different clients. If httpx is already installed it is used instead, purely for connection pooling; nothing else changes and nothing requires it.

Install

pip install ./clients/odms            # or: pip install ./clients/odms[pooled]

Or vendor it: the odms/ package is four files and imports nothing outside the standard library.

Use

from odms import OdmsClient

with OdmsClient("https://odms.tmtc.yksa.space", token=TOKEN) as odms:
    element = odms.latest("iss")            # newest OMM, by epoch
    print(element["tle"])

    past = odms.at("iss", "2026-04-01T00:00:00Z")
    span = odms.history("iss", start, end, limit=500)

    xml  = odms.download(internal_id="iss", format="omm_xml")
    oem  = odms.oem("iss", start, stop, step_s=60)      # token

base_url is the site root, not the API prefix. A token is optional: without one you get the public catalogue and every read-only endpoint, which is what most consumers need. With one you also see non-public satellites and can reach the gated endpoints — OEM generation, message push, frame transforms, TLE fitting, bulk propagation.

Methods return parsed JSON (dict/list) or, for the rendered formats, the body as text. Deliberately not model classes: ODMS adds fields as the catalogue grows, and mapping them onto fixed classes turns each addition into a client release.

Endpoints

Method	What
`query(format=…, **filters)`	The one element-search endpoint. Everything else below is a shortcut over it.
`latest(key)` / `at(key, when)` / `history(key, start, end)`	The three questions worth asking of an element history. `None` / `[]` when there is nothing.
`download(format=…, **filters)`	TLE text, OMM XML, CSV, KVN, or a converted element set.
`satellites()` / `satellite(key)` / `find(key)`	The catalogue. `find` returns `None` where `satellite` raises.
`sources()`	Configured public sources with their last-run status.
`opm(key)` / `oem(key, start, stop)`	Generate CCSDS messages. OEM needs a token.
`element_sets(key)` / `state(key, frame)`	Converted element sets, and a state in a named frame.
`messages(key)` / `message(id)` / `push_message(text)`	Stored external OPM/OEM. Push needs a token.
`transform(frame, …)` / `tle_from_oem(…)` / `propagate(key, timestamps)`	The gated compute endpoints.
`decay_runs(key)` / `decay_run(id)` / `decay_latest(key)`	Re-entry forecasts. `decay_latest` returns `None` when there is no forecast — a normal state, not an error.

key is resolved the way ODMS resolves it: internal id, then NORAD catalog number, then COSPAR designator.

Errors

Everything inherits OdmsError, so a caller that only cares whether ODMS answered can catch that one.

Exception	Meaning
`TransportError`	Never reached the server: DNS, TCP, TLS, read timeout.
`NotFound`	No such object — or a non-public one seen anonymously. Indistinguishable on purpose.
`Unauthorized`	The endpoint is token-gated and the token was missing or invalid.
`RateLimited`	Per-IP hourly budget spent, after the automatic retries. Carries `retry_after`.
`ServiceUnavailable`	ODMS or its propagation sidecar is busy or down.
`HTTPError`	Anything else 4xx/5xx. Carries `status`, `body`, `detail`.

Retries

429, 502, 503 and 504 are retried with exponential backoff and jitter, honouring Retry-After. 500 is not: it means ODMS took the request and broke on it, and repeating it breaks it again.

Transport failures are retried for reads only. A POST whose outcome is unknown is not repeated — push_message that timed out may well have stored the message, and a retry would store a second copy. If you need to recover one, check messages() and push again yourself.

Configuration

OdmsClient(
    base_url,
    token=None,          # bearer token, from Core > API tokens in the admin
    timeout_s=30.0,
    max_retries=3,
    user_agent="odms-client/1.0",
    session=None,        # pass your own httpx.Client to share a pool
)

The API prefix and the element-query path are class attributes (api_prefix, query_path), so a deployment mounted elsewhere — or one still serving the older tle/query/ alias — is reachable without subclassing.

Thread-safe. Not fork-safe: build one client per process.

4.6 KiB Raw Blame History