TLE Catalog API

The Catalog API manages Two-Line Element sets (TLEs) for all tracked satellites. It pulls orbital data from CelesTrak’s GP API and optionally from Space-Track, storing records locally for propagation by the tracking engine. Background update tasks keep the catalog current, and search/import endpoints let you add individual satellites on demand.

Update TLEs

Trigger a background TLE refresh from the CelesTrak GP API for all configured satellite groups. The request returns immediately; the actual fetch and database update runs asynchronously.

POST /api/catalog/tle/update

Response

{
  "status": "updating",
  "message": "TLE update started in background"
}

Tip

Default satellite groups fetched from CelesTrak: amateur, visual, stations, weather, noaa, and starlink. Debris groups (fengyun-1c-debris, cosmos-2251-debris, iridium-33-debris, cosmos-1408-debris, analyst objects) are also available but typically configured separately due to their size.

Caution

TLEs have a limited shelf life. Propagation accuracy degrades the further you predict from the TLE epoch. For LEO satellites, a TLE older than a few days can introduce significant pointing error. Run updates regularly or before critical tracking sessions.

---

Space-Track Update

Trigger a background TLE update from Space-Track. This source provides authoritative orbital data from the 18th Space Defense Squadron catalog.

POST /api/catalog/spacetrack/update

Response

{
  "status": "updating",
  "message": "Space-Track update started in background"
}

Errors

Status	Detail
400	Space-Track credentials not configured in SPACETRACK_USER / SPACETRACK_PASS

Note

Space-Track requires a free account at space-track.org. Set the SPACETRACK_USER and SPACETRACK_PASS environment variables before using this endpoint. If credentials are missing, the endpoint returns a 400 error rather than silently failing.

---

Catalog Status

Returns the last update time, record count, and current status for each configured data source (CelesTrak groups, Space-Track, etc.).

GET /api/catalog/status

Response

{
  "sources": [
    {
      "name": "celestrak-amateur",
      "type": "celestrak",
      "last_updated": "2026-02-14T18:30:00",
      "status": "ok",
      "error": null
    },
    {
      "name": "celestrak-stations",
      "type": "celestrak",
      "last_updated": "2026-02-14T18:30:05",
      "status": "ok",
      "error": null
    },
    {
      "name": "spacetrack",
      "type": "spacetrack",
      "last_updated": null,
      "status": "never_fetched",
      "error": null
    }
  ]
}

Tip

Use the status endpoint to check whether your TLEs are stale before starting a tracking session. If last_updated is more than 24 hours old for LEO targets, consider triggering a refresh first.

---

CelesTrak Search

Search the CelesTrak catalog by satellite name. Results are returned directly from CelesTrak and are not imported into the local database. Use this to find a satellite’s NORAD catalog number before importing it.

GET /api/catalog/celestrak/search?q={name}

Parameters

Name	Type	Required	Description
q	string	Yes	Search term (minimum 2 characters)

Response

{
  "query": "ISS",
  "results": [
    {
      "norad_id": 25544,
      "name": "ISS (ZARYA)",
      "intl_designator": "1998-067A",
      "object_type": "PAYLOAD",
      "rcs": 925.0,
      "is_active": true,
      "tle_epoch": "2026-02-14T12:00:00"
    }
  ],
  "count": 1
}

Response Fields

Field	Type	Description
norad_id	int	NORAD catalog number (unique satellite identifier)
name	string	Satellite common name
intl_designator	string or null	International designator (launch year, number, piece)
object_type	string or null	Object classification: PAYLOAD, ROCKET BODY, DEBRIS, etc.
rcs	float or null	Radar cross section in m²
is_active	bool	Whether the satellite is operationally active
tle_epoch	string or null	Epoch timestamp of the most recent TLE

Tip

The search queries CelesTrak’s GP API in real time and does not touch the local database. To add a result to your local catalog, pass its norad_id to the import endpoint below.

---

CelesTrak Import

Import a specific satellite into the local catalog by its NORAD catalog number. The satellite’s TLE is fetched from CelesTrak and stored locally for tracking. Optionally assigns the satellite to a named group.

POST /api/catalog/celestrak/import

Request Body

{
  "norad_id": 25544,
  "group": "stations"
}

Field	Type	Required	Description
norad_id	int	Yes	NORAD catalog number of the satellite to import
group	string	No	Group name to assign the satellite to (e.g. “amateur”, “weather”)

Response

{
  "status": "imported",
  "norad_id": 25544,
  "name": "ISS (ZARYA)",
  "object_type": "PAYLOAD"
}

Errors

Status	Detail
404	No satellite found on CelesTrak with the given NORAD ID

Note

Importing a satellite also rebuilds the search text index for that record, enabling semantic search across the catalog. If the satellite already exists locally, the import updates its TLE only when the CelesTrak epoch is newer than the stored one.

---

Refresh Single TLE

Refresh the TLE for a single satellite already in the local catalog. Fetches the latest orbital elements from CelesTrak and updates the local record if the new epoch is more recent.

POST /api/catalog/tle/refresh/{norad_id}

Parameters

Name	Type	Required	Description
norad_id	int	Yes	NORAD catalog number (path parameter)

Response

{
  "status": "refreshed",
  "norad_id": 25544,
  "name": "ISS (ZARYA)",
  "tle_epoch": "2026-02-14T14:22:00"
}

Errors

Status	Detail
404	No satellite found on CelesTrak with the given NORAD ID

Tip

Use this endpoint to refresh a single high-priority target right before a pass, rather than running a full catalog update. This is faster and puts less load on CelesTrak’s API.