Skip to main content

Satellite Operations

Base path: /v1

Auth required: Yes (JWT Bearer via Authorization: Bearer <token>)

What this service does

  • Search satellites by country/operator, purpose, constellation, or a flexible field/text
  • Get current position and an adaptive-length future trajectory from TLEs
  • Fetch lists like constellations or purposes for a given country/operator

How it works

  • Reads satellite metadata from NoradDb
  • Pulls latest TLE from TleData (fallback and staleness warnings built-in)
  • Uses Skyfield to compute valid lat/lon/alt positions and a sensible trajectory window

Endpoints

Search NORAD with filters​

  • POST /v1/norad_db/
  • Body:
{
  "country_operator": ["USA"],
  "detailed_purpose": ["COMMUNICATIONS"],
  "constellation_name": ["STARLINK"]
}
  • 200 Response (array of satellites):
[
  {
    "id": 1,
    "norad_id": "25544",
    "satellite_name_official": "ISS (ZARYA)",
    "country_operator": "USA",
    "constellation_name": null,
    "purpose": "SPACE STATION",
    "detailed_purpose": "RESEARCH"
  }
]
  • Errors: 400 (missing country_operator), 500

Flexible search (field + text)​

  • POST /v1/search/
  • Body:
{
  "search_text": "STARLINK",
  "search_field": "constellation_name"
}
  • 200 Response: array of NoradDbResponse
  • Errors: 400 (empty search text or invalid field), 500

Current position and trajectory​

  • POST /v1/get_current_position/
  • Body:
{ "norad_id": 25544 }
  • 200 Response (truncated):
{
  "norad_id": 25544,
  "timestamp": "2025-02-05T12:35:00Z",
  "latitude": 34.05,
  "longitude": -118.24,
  "altitude_km": 418.2,
  "orbital_period_minutes": 92.7,
  "trajectory_duration_minutes": 90,
  "trajectory": [{"timestamp":"2025-02-05T12:36:00Z","latitude":34.1,"longitude":-118.2,"altitude_km":418.3}]
}
  • Errors: 400 (invalid NORAD ID or insufficient trajectory points), 404 (TLE not found), 500

Get constellation names​

  • POST /v1/get_constellation/
  • Body:
{ "country_operator": ["USA","EUROPE"] }
  • 200 Response:
{ "result": ["STARLINK", "GALILEO"] }
  • Errors: 400, 500

Get detailed purposes​

  • POST /v1/get_detailed_purpose/
  • Body:
{ "country_operator": ["USA"] }
  • 200 Response:
{ "result": ["COMMUNICATIONS","EARTH OBSERVATION"] }
  • Errors: 400, 500

Notes:

  • All responses validate lat/lon bounds and numeric sanity; negative altitudes get fallback handling.