GPS Settings

GPS display preferences are stored as system-global key-value pairs in the SystemConfig table. These settings apply to all users — GPS is a system-internal feature, not per-user.

Available Keys

Key	Default	Values	Description
gps.speed_unit	"kmh"	kmh, mps, mph, knots	Speed unit for display
gps.coordinate_format	"decimal"	decimal, dms	Coordinate display format
gps.timezone	"utc"	utc, local	Timestamp display timezone
gps.retention_days	null	integer or null	Data retention window; null = unlimited

REST Endpoints

Method	Path	Permission	Description
GET	/v1/settings	settings:read	List all system settings
GET	/v1/settings/{key}	settings:read	Get single setting
PATCH	/v1/settings/{key}	settings:write	Update setting value

GraphQL

• settings(prefix: String) → [GqlSystemConfig] — pass "gps." to fetch all GPS settings
• setting(key: String) → GqlSystemConfig
• updateSetting(key: String!, value: JSON!) → GqlSystemConfig

Examples

Get all GPS settings:

GET /v1/settings?prefix=gps.

Response:

[
  { "key": "gps.speed_unit", "value": "kmh", "description": "Preferred speed unit: kmh, mps, mph, knots" },
  { "key": "gps.coordinate_format", "value": "decimal", "description": "Coordinate format: decimal, dms" },
  { "key": "gps.timezone", "value": "utc", "description": "Display timezone: utc, local" },
  { "key": "gps.retention_days", "value": null, "description": "Data retention in days, null = unlimited" }
]

Update speed unit:

PATCH /v1/settings/gps.speed_unit
{ "value": "knots" }

Audit

Every PATCH on a setting emits a setting_updated audit event with the key, old value, and new value.

Behaviour Notes

• Settings keys are pre-seeded in the migration. No endpoint exists to create new keys.
• Values are stored as JSONB — strings must be quoted ("kmh" not kmh), numbers as-is, null as null.
• gps.retention_days — when set to an integer, the API prunes GPS data older than N days. Pruning schedule is application-internal (not exposed as an API).

RBAC Permissions

Permission	Description
settings:read	View system settings
settings:write	Modify system settings