sat-spotter-api
Author
Stateless FastAPI backend serving satellite pass predictions over HTTP - the same Skyfield computation as the CLI, wrapped in a REST interface with Pydantic models. TLEs are cached on disk; no database or auth required. Designed to back a Flutter front-end.
- Python
- FastAPI
- Skyfield
- Pydantic
- Uvicorn
ENDPOINTS
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.
DESIGN: 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.
STACK
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.
KEY TAKEAWAYS
- Stateless REST API - location + NORAD IDs in, pass predictions out
- Six endpoints: satellite search, catalog, metadata, passes, trajectory
- Disk-based TLE cache with configurable TTL; no database required
- All settings overridable via environment variables
- Full OpenAPI docs at /docs; tested with Celestrak mocked