API リファレンス¶

モバイル UI を配信するのと同じ Web サーバーが、小さな読み取り中心の REST API と 1 本の WebSocket を公開しています。LAN 内のみ・認証なし・ポート 8080 です。

http://<デスクトップの IP>:8080/api/...
ws://<デスクトップの IP>:8080/ws/tracking

エラーは FastAPI の形式です：{"detail": "<メッセージ>"} と 4xx/5xx ステータス（404＝未知の衛星、422＝日時不正、503＝エンジン／リグ未準備、 409＝リグ操作に接続が必要）。

サーバーのソース：src/web/app.py

REST エンドポイント¶

衛星¶

GET /api/satellites — 任意で ?group=（amateur、weather …、 operational、または fav:<id>）。

[
  {
    "norad_cat_id": 25544,
    "name": "ISS (ZARYA)",
    "alt_names": ["ZARYA"],
    "status": "alive",
    "updated_at": "2026-05-10T09:00:00Z",
    "amsat_status": "operational",
    "favorite_group": 0,
    "tle_no_result_since": null
  }
]

GET /api/favorites — 同じ形式。いずれかのカスタムグループに属する全衛星。

GET /api/custom-groups — [{ "id": 1, "name": "Favorite 1", "sort_order": 0 }]

PUT /api/satellites/{norad}/favorite-group — ボディ { "group_id": 1 } （0 で解除）。204。

トランスミッター¶

GET /api/satellites/{norad}/transmitters

[
  {
    "uuid": "…", "norad_cat_id": 25544, "description": "Voice Repeater",
    "type": "Transponder",
    "downlink_low": 145800000, "downlink_high": 145800000,
    "uplink_low": 437800000, "uplink_high": 437800000,
    "mode": "FM", "invert": false, "baud": null,
    "ctcss_tone": 67.0, "ctcss_tone_type": "…",
    "alive": true, "source": "satnogs", "manual_override": false, "notes": ""
  }
]

周波数は Hz です。downlink_low／downlink_high はトランスポンダーの帯域では異なり、固定チャンネルでは同じ値になります。

パス¶

GET /api/satellites/{norad}/passes

クエリ	既定	備考
`hours`	`24`	予測窓、`0 < hours ≤ 168`
`min_el`	`5`	最大仰角の下限（度）
`track`	`false`	パスごとに 15 秒間隔の `(az, el)` サンプルを含める
`from_dt`, `to_dt`	—	ISO 8601。指定すると `hours` を上書き

[
  {
    "norad_cat_id": 25544,
    "aos": "2026-05-10T12:45:00+00:00",
    "tca": "2026-05-10T12:53:00+00:00",
    "los": "2026-05-10T13:01:00+00:00",
    "max_elevation_deg": 72.4,
    "max_elevation_time": "2026-05-10T12:53:00+00:00",
    "aos_azimuth_deg": 201.0,
    "los_azimuth_deg": 22.0,
    "duration_s": 960.0,
    "duration_seconds": 960.0,
    "quality": "excellent",
    "track_points": null
  }
]

quality は excellent（≥60°）／good（≥30°）／fair（≥10°）／low。

GET /api/passes/group — ?group=（既定 amateur）、from_dt、to_dt、 min_el。各項目に sat_name と amsat_status が加わり、方位の詳細は省かれます。

TLE・ステータス・位置¶

GET /api/tle/status — 衛星ごとの quality_score、epoch、fetched_at、 source。

GET /api/status — { "version", "status", "satellite_count", "tle_count", "uptime_s" }

GET /api/amsat — { "<designator>": "<status>" } のマップ。

GET /api/location — 自局 QTH（latitude_deg、longitude_deg、 elevation_m、source、city、country、status_text）。未設定なら 404。

POST /api/location/browser — ボディ { "latitude", "longitude", "accuracy_m"?, "elevation_m"? }。ブラウザの測位結果を保存。

Rig／ローテーター（モバイルの Antenna タブ）¶

いずれも 204 を返します。利用不可なら 503、未接続なら 409。

POST /api/rig/toggle — ドップラー補正の切り替え
POST /api/rot/toggle — ローテーター追尾の切り替え
POST /api/rig/connect — ボディ { "norad": 25544, "xpdr_uuid": "…" }
POST /api/rig/disconnect

WebSocket¶

ws://<host>:8080/ws/tracking?norad=<id>（既定 25544）。その 1 衛星について毎秒 1 通の JSON：

{
  "norad": 25544,
  "timestamp": "2026-05-10T12:00:00+00:00",
  "elevation_deg": 45.12,
  "azimuth_deg": 180.34,
  "range_km": 412.5,
  "range_rate_km_s": -2.134567,
  "is_above_horizon": true
}

エンジン未設定または TLE 欠落時は { "norad": <id>, "error": "<メッセージ>" }。

例¶

# 今後 3 日、仰角 20° 以上の ISS のパス
curl "http://localhost:8080/api/satellites/25544/passes?hours=72&min_el=20" | jq '.[].aos'

import websockets, asyncio, json

async def main():
    url = "ws://localhost:8080/ws/tracking?norad=25544"
    async with websockets.connect(url) as ws:
        while True:
            print(json.loads(await ws.recv()))

asyncio.run(main())