sat-spotter-api
A FastAPI backend that wraps the same Skyfield-based satellite pass computation used by the sat-spotter CLI and serves it over HTTP. Stateless by design - the client sends a location and a list of NORAD IDs; the server fetches TLEs, computes, and returns typed JSON.
- Python
- FastAPI
- Skyfield
- Pydantic
- Uvicorn
01Endpoints
The API exposes two routers: satellites (search CelesTrak by name, fetch a curated catalog, retrieve orbit metadata for a NORAD ID) and passes (predict passes for up to 50 satellites over a configurable window, with optional naked-eye visibility filtering; return sky-chart trajectory points for a specific pass).
All endpoints are GET-only - the API is read-only by design. Interactive docs are available at /docs via FastAPI's built-in OpenAPI renderer.
02Design: stateless and portable
No database, no auth, no persistent state. TLEs are fetched from CelesTrak and cached on disk with a configurable TTL (default 4 hours). The curated satellite catalog is a plain JSON file - editing it requires no code change. All settings (cache path, TTL, CORS origins, max NORAD IDs per request, HTTP timeout) are environment-variable overrides over sensible defaults.
The stateless design means the service can be deployed anywhere a Python 3.12 process can run - a VPS or a container - with no external dependencies beyond the file system.
03Stack
FastAPI with Uvicorn handles HTTP. Skyfield drives all orbital computation. Pydantic models define the response schema. httpx fetches TLEs. The test suite mocks Celestrak and covers endpoints and core computation separately.
Next
OrbitLens