How the index is built

The site is never coupled to a third-party feed. Every value passes through the same chain, and each stage keeps what the previous one produced:

1. Connector — a scheduled worker per upstream feed (celestrak_gp, celestrak_groups, celestrak_satcat, derived_analytics). Each run is recorded with duration, record counts, a payload hash and any error; repeated failures open a circuit breaker.
2. Raw snapshot — the exact upstream payload is stored gzip-compressed on disk and indexed in raw_records before anything is parsed. Only payloads whose hash changed are processed; unchanged responses are logged as such.
3. Normalize — rows are parsed into a common shape (identifiers, names, dates, element sets). Suspiciously short responses (for example a catalog with far fewer than 50 000 rows) are rejected as truncated rather than treated as “no data”.
4. Entity resolution — each normalized row is matched to an existing canonical object (next section) or creates a new one. Ambiguous matches go to a manual review queue.
5. Canonical store — one row per object in satellites, an append-only orbital_elements history with orbital_state pointing at the latest epoch, field-level history and field_provenance (source, observation time, confidence) for every accepted value. Objects missing from an upstream response are never deleted.
6. Derived — materialized statistics, constellation/operator/country aggregates, the search index and detected events are refreshed by derived_analytics (hourly) using the versioned metric definitions below.
7. API → web — the public JSON API reads only the canonical and derived layers; the website is a client of that API. Positions are computed at request time (see orbit calculation).

Sources carry a numeric priority; when two sources describe the same field the higher-priority value is kept and the other is still recorded in provenance. In practice each field family has one primary source today:

Matching an incoming row to a canonical object follows a strict priority; the first rule that yields exactly one candidate wins:

1. NORAD catalog number — if the row has a NORAD id already known, it is the same object.
2. COSPAR designator — only when the row has no NORAD id, and only if exactly one canonical object carries that designator.
3. Exact normalized name — only when the row has no NORAD id, against canonical objects that also lack one, and only if the name is unique.
4. Create — otherwise a new canonical object is created with a ULID and a slug (name-norad, de-duplicated with a numeric suffix).

Anything ambiguous — a COSPAR id that maps to several objects, a name shared by several objects, or a NORAD id that appears alongside a different existing designator — is never merged automatically. It is written to manual_review_queue with both candidates and a confidence; an operator decides merge, keep separate or dismiss. Merges move aliases, identifiers and element history to the kept object and are journaled in entity_merges with a snapshot of the removed row, so they can be audited or reversed.

Positions are propagated with SGP4 (the python-sgp4 implementation of the Vallado et al. reference code, vectorised with SatrecArray) using the WGS-72 gravity constants — the model the element sets were fitted against. Inputs are the OMM element sets from CelesTrak (epoch, mean motion, eccentricity, inclination, RAAN, argument of perigee, mean anomaly, B*, first derivative of mean motion).

SGP4 yields a position vector in the TEME frame. It is rotated to Earth-fixed coordinates (ECEF) about the Z axis by the Greenwich Mean Sidereal Time of the requested instant (UT1 ≈ UTC; polar motion ignored, ≈ 10 m), then converted to geodetic latitude, longitude and altitude on the WGS84 ellipsoid by iteration. Velocity is the norm of the TEME velocity vector.

Derived geometry shown on satellite pages comes from the same element set: semi-major axis a = (μ / n²)^1/3 with μ = 398 600.4418 km³/s², perigee/apogee = a(1 ∓ e) − 6 378.137 km, period = 1440 / n minutes.

SGP4 is an analytical mean-element model: typical along-track error is of the order of a kilometre at epoch and grows by kilometres per day, faster for low, high-drag orbits and after manoeuvres. Positions shown on this site are therefore indicative: good for “where is it over the Earth right now”, not for pointing, conjunction or reentry work. Every position carries the epoch it was propagated from and its age.

Positions are computed on demand and never stored: the propagator keeps the latest element set of every object in memory and answers batch and single-object requests with a 30-second cache. Only element sets are persisted.

The rule is evaluated on the latest element set (or, for objects without GP data, on the SATCAT apsides with eccentricity estimated from perigee and apogee). Implementation order, as in orbital/elements.py:

Membership is assigned in two tiers. CelesTrak GP groups first: an object listed in a thematic group mapped to a constellation (for example starlink, oneweb, kuiper) is a source-backed member (method: celestrak_group). Documented name patterns second: payloads not covered by a group are matched against the regular expressions of the curated registry (method: name_pattern, derived). Membership history is kept with since/until dates; a member is never removed just because a group response was short.

The table below is the live registry — the exact patterns and groups the classifier uses right now.

Mission type is derived, in this order of preference (services/classify.py):

1. the service type of the matched constellation (communications, earth-observation, navigation, iot…);
2. otherwise the object type when it is decisive: rocket bodies → rocket-body, debris → debris, stations → station;
3. otherwise a documented name pattern from the curated registry (for example weather, GNSS or science families);
4. otherwise unknown. A later run never downgrades a known mission type to unknown.

No launch feed is ingested yet. Launches are derived from international designators: the first eight characters of a COSPAR id (YYYY-NNN) identify the launch, so every object sharing that prefix is attached to one launch row. The launch date and site are the earliest date and the site reported for those objects in SATCAT; the “primary” payload is the object whose piece letter is A; payload, object and on-orbit counts are recomputed after every catalog run. Objects with no COSPAR id (analyst objects) belong to no launch and are flagged.

SATCAT identifies the responsible party of every object with a short owner code. We map each code to a country (ISO 3166) and, when the owner is an organization, agency or intergovernmental body, to an operator entity. Joint programmes map to several countries’ programmes but a single primary country when one is defined. Unmapped codes raise an UNKNOWN_COUNTRY quality flag instead of guessing.

Every derived value on the site points at one of these definitions. The version changes whenever the rule changes; the inputs list the exact canonical columns the rule reads. None of them is a safety metric.

Two scales are in use, and both are shown rather than hidden behind an average:

• Per connector (/status/data, /sources): relative to the connector’s own interval — fresh under 3 × interval, aging under 12 ×, stale beyond; unavailable if it never succeeded, not enabled for planned connectors.
• Per object (satellite pages): the orbit is fresh under 12 h, aging from 12 to 48 h and stale after 48 h since the element epoch or the last successful orbital sync; catalog metadata uses 36 h / 96 h.

The health endpoint reports the worst connector freshness as the platform’s data status.

• Name-pattern classification errors. Constellation membership and mission type inferred from names can misfile objects with unusual or reused names (test payloads, renamed spacecraft, shared bus names). Group-backed memberships are more reliable than pattern-backed ones; both are labelled.
• Catalog latency. SATCAT status codes, decay dates and new-object entries lag reality by hours to weeks. A satellite can be operational before it is marked +, and decayed objects may stay “on orbit” until the catalog catches up.
• GEO drift and graveyard objects. Inclined, drifting or super-synchronous objects sit near the GEO/MEO/OTHER boundaries and may switch class between element sets.
• Analyst objects. Objects tracked without a COSPAR designator (and sometimes with temporary NORAD numbers) have no launch, owner or country and can later be re-identified — that is exactly the case the manual review queue exists for.
• Element-set age. Positions inherit the age of their elements; a stale feed means every live position on the site is stale, and the status page says so.
• Coverage. Only CelesTrak feeds are ingested today; government registries (Space-Track, UNOOSA), ESA DISCOS and GCAT are registered as planned sources but contribute nothing yet.