Search docs ⌘K
esc
Type to search across all documentation pages
Logistics

Tracking

Record GPS pings against entities. Pings are stored in a Durable Object for real-time access and can be queried as a history trail. All routes live under /logistics/* and require a token with logistics:read or logistics:write scope.

Send Ping

POST
/logistics/tracking/{entity_id}/ping
logistics:track0.0000008 tokens

Report an entity's current GPS position.

curl
curl -X POST https://api.saasignal.saastemly.com/logistics/tracking/{entity_id}/ping \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"lat":1,"lng":1}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.logistics.tracking.ping('ent_abc123', {
  lat: 40.7128, lng: -74.0060,
  speed: 35, heading: 90,
})
  1. Open Dashboard and select your project
  2. Go to Tracking and select an entity
  3. The entity's current position updates in real time on the map
Pings are typically sent from device SDKs or backend services, not from the dashboard.
Path param
Type
Description
entity_id required
string
Entity ID to update
Body field
Type
Description
lat required
number
Latitude (−90 to 90)
range ≥-90 .. ≤90
lng required
number
Longitude (−180 to 180)
range ≥-180 .. ≤180
heading
number
Compass heading in degrees (0–360)
range ≥0 .. ≤360
speed
number
Speed in km/h (≥ 0)
range ≥0
accuracy
number
GPS accuracy in meters (≥ 0)
range ≥0
recorded_at
string
ISO 8601 timestamp when the ping was recorded. Defaults to server time.
Error responses
401 Unauthorized
402 Insufficient tokens
404 Not found
429 Rate limited

Batch Ping

POST
/logistics/tracking/{entity_id}/ping/batch
logistics:track0.0000008 tokens per ping

Submit multiple GPS pings at once.

curl
curl -X POST https://api.saasignal.saastemly.com/logistics/tracking/{entity_id}/ping/batch \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"pings":[]}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.logistics.tracking.batchPing('ent_abc123', [
  { lat: 40.7128, lng: -74.0060, recorded_at: '2026-03-08T10:00:00Z' },
  { lat: 40.7135, lng: -74.0055, recorded_at: '2026-03-08T10:01:00Z' },
])
  1. Batch ping is an API-only operation for uploading historical GPS data
  2. Use the REST API or TypeScript SDK
Uploaded pings appear in the Tracking history view.
Path param
Type
Description
entity_id required
string
Entity ID to update
Body field
Type
Description
pings required
array
Array of ping objects (1–100 items). Each ping has: lat (−90 to 90, required), lng (−180 to 180, required), heading (0–360), speed (≥ 0), accuracy (≥ 0), recorded_at (ISO 8601)
1–100 items
Error responses
401 Unauthorized
402 Insufficient tokens
404 Not found
429 Rate limited

Live Tracking

GET
/logistics/tracking/{entity_id}/track
logistics:read

Subscribe to real-time location updates via WebSocket. Billing: per-minute connection cost.

curl
curl https://api.saasignal.saastemly.com/logistics/tracking/{entity_id}/track \
  -H "Authorization: Bearer sk_live_..."
typescript
// WebSocket connection for real-time tracking
const ws = ss.logistics.tracking.live('ent_abc123')
  1. Open Dashboard and select your project
  2. Go to Tracking and select an entity
  3. The map shows the entity's live position and trail in real time
Path param
Type
Description
entity_id required
string
Entity ID to track
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Ping History

GET
/logistics/tracking/{entity_id}/history
logistics:read0.0000008 tokens

Retrieve historical location pings.

curl
curl https://api.saasignal.saastemly.com/logistics/tracking/{entity_id}/history \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const trail = await ss.logistics.tracking.history('ent_abc123', { limit: 100 })
  1. Open Dashboard and select your project
  2. Go to Tracking and select an entity
  3. Switch to the History tab to see the GPS trail plotted on the map
Path param
Type
Description
entity_id required
string
Entity ID
Query param
Type
Description
limit
integer
Max pings to return (1–200). Default 50.
range ≥1 .. ≤200default 50
cursor
string
Pagination cursor from previous response
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited