Machine-readable API

PiFinder exposes a set of optional JSON and image endpoints under /api/ for automation and external tools. They are registered on the same web server that serves the PiFinder web interface, and by default they require no authentication, so any client on the same network can call them.

Everything is served relative to the PiFinder’s address, for example http://pifinder.local/api/status. JSON endpoints return application/json; image endpoints return image/png. When the data a call needs isn’t ready yet — no GPS lock, no plate solve, no IMU or SQM reading — that endpoint returns HTTP 503 with a short JSON note explaining why, rather than failing outright.

Status and data

These endpoints return JSON. /api/status is the convenient one-shot call; the rest let you fetch a single value on demand.

GET /api/status

Aggregated snapshot, fetching everything in one call: power_state, solve_state, camera_type, location, solution, datetime (both utc and local), imu, sqm and software_version.

GET /api/time

The current utc and local time plus the active timezone.

GET /api/location

The current GPS location (latitude, longitude, altitude, timezone and lock state). The GPS cache is refreshed before responding, and the call returns 503 if GPS is not locked.

GET /api/solution

The current plate-solve solution — RA, Dec, Roll, field of view and the matched-star statistics. Alt and Az are added when a location and time are available. Returns 503 if there is no valid solve yet.

GET /api/imu

The current IMU data (orientation and movement state). Returns 503 when no IMU is present or no reading is available.

GET /api/sqm

The latest Sky Quality Meter estimate of sky brightness. Returns 503 when no reading is available.

GET /api/visible_stars

Re-renders the star field for the current pointing and returns the visible stars as structured data, optionally with the rendered chart as a base64 PNG. It uses the camera solve (RA / Dec / Roll) so the result isn’t shifted by IMU dead-reckoning.

The response carries the solve source and pointing, the filters that were applied, a count and label_count, and a visible_stars array. Each star includes its catalog fields, a display_name, and a label flag (with label_reason) marking the stars suggested for on-screen labelling. Rendered star positions are returned in the coordinate system set by render_size.

Query parameters for /api/visible_stars:

render_mag_limit: Magnitude limit for the stars returned for rendering. Default: 5.5. The legacy name mag_limit is still accepted.
label_mag_limit: Magnitude limit for the stars suggested for labelling. Default: 2.5.
max_labels: Maximum number of suggested labels, clamped to 0–30. Default: 5. If too few stars fall within label_mag_limit, the brightest stars in the field are added to reach this count.
use_camera_solve: Prefer the camera solve over the integrated, IMU-corrected solution. Default: true.
fov: Rendering field of view in degrees. Default: the solve’s FOV, or 10.2.
render_size: Output resolution in pixels, clamped to 128–4096. Star positions are returned in this coordinate system. Default: 1088.
constellation_brightness: Brightness of the constellation lines (0–255). Default: 32.
shade_frustrum: Whether to shade the camera frustum. Default: true.
include_image: Include the rendered star chart in the response as a base64-encoded PNG. Default: false.

Images

These endpoints return a PNG directly, which makes them easy to embed in a browser or save to a file.

GET /api/screen: The current 128×128 device screen as a PNG — the same image shown on the OLED.
GET /api/camera/raw: The raw CMOS camera image as a PNG, when one is available; otherwise 503.
GET /api/camera/debug: The most recent solver debug frame from the debug-dump directory, as a PNG; 503 if none have been written.

Control

These endpoints accept a POST with a JSON body and change the state of the PiFinder, so use them with care.

POST /api/key: Simulate a keypad press. JSON body: {"button": "UP"} (a button name) or {"button": 1} (a raw key code).
POST /api/stop: Cleanly shut down the entire PiFinder application, reproducing a terminal Ctrl-C. Optional JSON body {"delay": <seconds>} (default 0.5, capped at 5) sets how long to wait before signalling, so the HTTP response can flush first.

Example

# One-shot status, then individual values
curl http://pifinder.local/api/status
curl http://pifinder.local/api/solution
curl http://pifinder.local/api/sqm

# Visible stars, with the rendered chart embedded as a base64 PNG
curl "http://pifinder.local/api/visible_stars?render_mag_limit=5.5&include_image=true"

# Save the current screen to a file
curl http://pifinder.local/api/screen -o screen.png

# Simulate pressing the UP button
curl -X POST http://pifinder.local/api/key \
     -H "Content-Type: application/json" \
     -d '{"button": "UP"}'