Skip to content

Web API Reference

FBSAT59 exposes a REST API and WebSocket for integration with external tools.

Base URL

http://localhost:8080/api

Or from remote machine on LAN:

http://192.168.x.x:8080/api  (replace with your IP)

REST Endpoints

Get All Satellites

GET /satellites

Response: 

[
  {
    "norad_cat_id": 25544,
    "name": "ISS (ZARYA)",
    "status": "alive",
    "uplink_mhz": 144.39,
    "downlink_mhz": 145.80,
    "updated_at": "2024-01-15T10:30:00Z"
  },
  ...
]

Get Satellite by NORAD ID

GET /satellites/{norad_id}

Example: 

GET /satellites/25544  (ISS)

Get Upcoming Passes

GET /satellites/{norad_id}/passes?days=7

Response: 

[
  {
    "aos": "2024-01-15T12:45:00Z",
    "los": "2024-01-15T13:15:00Z",
    "max_elevation_deg": 72,
    "duration_seconds": 1800,
    "quality": "excellent"
  },
  ...
]

Get Transmitters

GET /satellites/{norad_id}/transmitters

Response: 

[
  {
    "uuid": "satnogs-12345",
    "downlink_mhz": 145.800,
    "uplink_mhz": 144.390,
    "mode": "FM",
    "ctcss_tone": 67.0,
    "description": "ISS Voice Repeater"
  },
  ...
]

Get Current Status

GET /status

Response: 

{
  "version": "0.3.50",
  "uptime_seconds": 3600,
  "location": {
    "latitude": 35.6762,
    "longitude": 139.6503,
    "elevation_m": 35
  },
  "rig_connected": true
}

WebSocket Connection

Real-time tracking data via WebSocket:

WS /ws/tracking

Connect: 

ws = new WebSocket('ws://localhost:8080/ws/tracking');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data);
};

Received Data (every 1–2 seconds): 

{
  "satellites": [
    {
      "norad_id": 25544,
      "name": "ISS",
      "azimuth_deg": 247.5,
      "elevation_deg": 34.2,
      "range_km": 1234,
      "velocity_kmps": 7.65,
      "is_visible": true
    },
    ...
  ]
}

Usage Examples

Python

import requests

# Get ISS passes for next 7 days
resp = requests.get('http://localhost:8080/api/satellites/25544/passes?days=7')
passes = resp.json()

for pass_data in passes:
    print(f"AOS: {pass_data['aos']}, Max Elevation: {pass_data['max_elevation_deg']}°")

JavaScript

// Get transmitter frequencies
fetch('http://localhost:8080/api/satellites/25544/transmitters')
  .then(r => r.json())
  .then(transmitters => {
    transmitters.forEach(tx => {
      console.log(`${tx.description}: ${tx.downlink_mhz} MHz`);
    });
  });

Bash

# Get all satellites
curl http://localhost:8080/api/satellites | jq '.[] | .name'

# Get ISS passes
curl "http://localhost:8080/api/satellites/25544/passes?days=7" | jq '.'

Rate Limiting

  • No authentication required (local network only)
  • No rate limiting
  • WebSocket: 1–2 Hz update rate

Error Responses

404 Not Found

{
  "error": "Satellite not found",
  "norad_id": 99999
}

400 Bad Request

{
  "error": "Invalid date format",
  "detail": "Use ISO 8601 format (YYYY-MM-DD)"
}

Integration Ideas

  • Wavelog integration: Import TLE, pass times
  • Custom tracking dashboard: Real-time web app
  • Logger bot: Post QSO updates to Slack/Discord
  • Mobile app: Client for remote satellite tracking

Source Code

API server: src/web/api.py (FastAPI)

Feel free to extend or customize for your needs!

Next Steps