Satellites API

The Satellites API provides access to the satellite catalog, including TLE (Two-Line Element) data, catalog management, and CelesTrak integration. Satellite data is sourced from CelesTrak and Space-Track.org.

List Satellites

Retrieve a paginated list of satellites, with optional filtering by group, name, or object type.

GET /api/satellites

Query Parameters

Parameter	Type	Default	Description
group	string	—	Filter by satellite group (e.g. amateur, stations)
q	string	—	Search satellites by name (case-insensitive)
object_type	string	—	Filter by object type (PAYLOAD, ROCKET BODY, DEBRIS)
limit	int	50	Results per page (max 200)
offset	int	0	Pagination offset

Response

{
  "satellites": [
    {
      "norad_id": 25544,
      "name": "ISS (ZARYA)",
      "intl_designator": "1998-067A",
      "tle_epoch": "2026-02-14T12:00:00",
      "orbit_type": "LEO",
      "object_type": "PAYLOAD",
      "is_active": true,
      "groups": ["stations", "visual"]
    }
  ],
  "count": 1
}

Examples

curl

# List all satellites in the amateur radio group
curl "https://space.warehack.ing/api/satellites?group=amateur&limit=10"

# Search for Starlink satellites
curl "https://space.warehack.ing/api/satellites?q=starlink&limit=20"

# Filter debris objects
curl "https://space.warehack.ing/api/satellites?object_type=DEBRIS&limit=50"

Python

import httpx

resp = httpx.get(
    "https://space.warehack.ing/api/satellites",
    params={"group": "amateur", "limit": 10},
)
data = resp.json()
for sat in data["satellites"]:
    print(f"{sat['norad_id']}: {sat['name']}")

---

Get Satellite by NORAD ID

Retrieve detailed information for a single satellite by its NORAD catalog number.

GET /api/satellites/{norad_id}

Path Parameters

Parameter	Type	Description
norad_id	int	NORAD catalog number

Response

{
  "norad_id": 25544,
  "name": "ISS (ZARYA)",
  "intl_designator": "1998-067A",
  "tle_epoch": "2026-02-14T12:00:00",
  "orbit_type": "LEO",
  "object_type": "PAYLOAD",
  "is_active": true,
  "groups": ["stations", "visual"]
}

Error Responses

Status	Description
404	Satellite with that NORAD ID not found

Examples

# Get ISS details
curl "https://space.warehack.ing/api/satellites/25544"

# Get Hubble Space Telescope
curl "https://space.warehack.ing/api/satellites/20580"

---

Satellite Images

Retrieve an image for a satellite. The image endpoint resolves through a three-tier system:

1. Wikipedia/Wikimedia Commons — spacecraft renders and photos for well-known satellites
2. NASA Image Library — photos for notable spacecraft
3. Generated orbital diagram — a unique SVG computed from TLE orbital parameters (inclination, eccentricity, altitude)

Every satellite returns a meaningful image. There are no empty placeholders.

GET /api/images/satellite/{norad_id}

Path Parameters

Parameter	Type	Description
norad_id	int	NORAD catalog number

Response

Returns image bytes with the appropriate Content-Type (image/jpeg or image/svg+xml). Custom headers indicate the image source:

Header	Values
X-Image-Source	wikipedia, nasa, orbital-diagram
X-Image-Credit	Attribution string (e.g. Wikimedia Commons, NASA)

Examples

# Fetch ISS image (likely a Wikipedia photo)
curl -o iss.jpg "https://space.warehack.ing/api/images/satellite/25544"

# Fetch a less well-known satellite (will get an orbital SVG)
curl -o sat.svg "https://space.warehack.ing/api/images/satellite/43226"

---

Catalog Management

These endpoints manage the satellite catalog — triggering TLE updates, searching CelesTrak, and importing new satellites.

Update TLEs from CelesTrak

Trigger a background TLE update for all tracked satellites.

POST /api/catalog/tle/update

Response

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

Note

TLE updates run asynchronously. The endpoint returns immediately while data is fetched in the background. TLEs are also refreshed automatically on a configured schedule.

---

Refresh Single TLE

Refresh the TLE for one satellite by NORAD ID.

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

Path Parameters

Parameter	Type	Description
norad_id	int	NORAD catalog number

Response

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

---

Update from Space-Track

Trigger a background update from Space-Track.org. Requires SPACETRACK_USER and SPACETRACK_PASS to be configured.

POST /api/catalog/spacetrack/update

Error Responses

Status	Description
400	Space-Track credentials not configured

---

Catalog Status

Check the status of all catalog data sources and their last update times.

GET /api/catalog/status

Response

{
  "sources": [
    {
      "name": "celestrak-amateur",
      "type": "tle",
      "last_updated": "2026-02-14T10:30:00",
      "status": "ok",
      "error": null
    }
  ]
}

---

Search CelesTrak

Search the CelesTrak database by satellite name. Results are not imported into the local catalog — use the import endpoint to add them.

GET /api/catalog/celestrak/search

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search query (min 2 characters)

Response

{
  "query": "NOAA",
  "results": [
    {
      "norad_id": 43013,
      "name": "NOAA 20",
      "intl_designator": "2017-073A",
      "object_type": "PAYLOAD",
      "rcs": 5.2,
      "is_active": true,
      "tle_epoch": "2026-02-14T08:00:00"
    }
  ],
  "count": 1
}

---

Import from CelesTrak

Import a satellite into the local catalog by NORAD ID. Optionally assign it to a group.

POST /api/catalog/celestrak/import

Request Body

{
  "norad_id": 43013,
  "group": "weather"
}

Field	Type	Required	Description
norad_id	int	Yes	NORAD catalog number to import
group	string	No	Group name to assign the satellite to

Response

{
  "status": "imported",
  "norad_id": 43013,
  "name": "NOAA 20",
  "object_type": "PAYLOAD"
}

Error Responses

Status	Description
404	No satellite found on CelesTrak with that ID