Locator Service API (v1.0)

Designed for:

Elderly tracking
Pet safety
Disabled assistance
MAC-auth only / no public join

Authentication

Only pre-authorized device MACs may use the /locator/* endpoints
MAC binding is performed via /device/authorize or via offline QR sync
Optional: signed heartbeat confirmation (for spoof detection)

🔁Core API Endpoints

`POST /locator/register`

Registers a locator-enabled device under a trusted MAC.

json{
  "mac": "A1:B2:C3:D4:E5:F6",
  "label": "Grandma Pendant",
  "type": "elderly", // or pet, child, etc.
  "pubkey": "..." // optional for signed beacons
}

Response:

json{ "locatorId": "locator_9238", "status": "registered" }

`POST /locator/ping`

Submit a location update or beacon event.

json{
  "mac": "A1:B2:C3:D4:E5:F6",
  "location": {
    "lat": 40.7128,
    "lon": -74.0060
  },
  "signal": "ok", // or "panic", "lost", "low_battery"
  "timestamp": "2025-06-01T12:00:00Z"
}

`GET /locator/status/:mac`

Returns the latest known status and location for a device.

Response:

json{
  "mac": "A1:B2:C3:D4:E5:F6",
  "location": { "lat": 40.7128, "lon": -74.0060 },
  "last_seen": "2025-06-01T12:00:00Z",
  "signal": "ok",
  "trusted": true
}

`POST /locator/alert`

Triggers a manual or automatic alert (e.g., fall detection or geofence breach).

json{
  "mac": "A1:B2:C3:D4:E5:F6",
  "alert_type": "fall_detected",
  "location": {
    "lat": 40.712,
    "lon": -74.001
  }
}

IPFS + SDR Capable

Locator pings and alerts can:
- Be queued to IPFS (locator_events.json)
- Be broadcast via SDR in mesh networks
Fully compatible with Validator Edition CID logging

CID-based event log format
QR-provisioning template
locator_api_server.py or .pyc for bundle

Sample sdk